Pagx

PAGX Skill

Pick the workflow that fits the request:

• HTML → PAGX — design a normal HTML page (or take an existing .html/URL) and convert it to PAGX with a single command. This is the way to create a new PAGX file. Best for non-technical users, visual descriptions in plain language, or when an HTML file/URL already exists. See HTML to PAGX Workflow.
• Update an existing PAGX — edit PAGX XML directly with full control over structure, constraints, and animation-ready layout. Best for modifying an existing .pagx, precise PAGX semantics, or hand-editing XML. See Update Workflow.

To create a PAGX from scratch, use HTML → PAGX. To modify an existing .pagx, use the Update Workflow.

Reference Lookup

When looking up PAGX syntax, attributes, node behavior, or CLI usage, consult the relevant reference:

CLI Setup

Before running any pagx command, ensure it is installed and meets the minimum version:

PAGX_MIN="0.4.47"
if ! command -v pagx &>/dev/null; then
  npm install -g @libpag/pagx
elif [ "$(printf '%s\n' "$PAGX_MIN" "$(pagx -v | awk '{print $2}')" | sort -V | head -1)" != "$PAGX_MIN" ]; then
  npm update -g @libpag/pagx
fi

Contributors working inside the libpag repo should skip the npm package and use the pagx they build from source instead, so every command runs their local changes — see Step 0 Case B.

The most frequently used command is pagx verify:

pagx verify input.pagx                      # diagnostics + layout.xml + screenshot
pagx verify --id "sectionId" input.pagx      # scoped to one section

--scale <factor> controls the screenshot resolution (default 1). Use --scale 2 for higher detail when visually inspecting screenshots. Output files are written to the current working directory: input.png (screenshot), input.layout.xml (computed bounds). With --id, outputs are input.{id}.png and input.{id}.layout.xml. Always run pagx verify from the same directory as the .pagx file. See references/cli.md for verify options and all other CLI commands (render, format, layout, bounds, font, import, export, preview).

pagx preview starts a live browser preview with hot reload — present the command to the user after generating a .pagx (see Live browser preview). Do not auto-launch it; let the user decide. Stop it with pagx preview stop when done. Prefer absolute .pagx paths in commands handed to the user because their shell may not be in the file's directory.

Update Workflow

When: User asks to modify, edit, adjust, or fix an existing PAGX file.

Before editing any PAGX code, read references/guide.md (spec rules, techniques, and especially §Common Pitfalls) and references/patterns.md (structural patterns for components and layouts). Read references/attributes.md as needed for attribute defaults.

Task tracking

At the start of every update task, create a task list to track progress:

• One task per section being changed (e.g., "Update section: heroCard")
• One task for the final Polish & QA pass

Mark each task in-progress before starting it and completed after all checks pass. Do NOT start the next task until the current one is completed.

Step 1: Assess the current file

Do:

1. Read the existing .pagx end to end to understand its structure — the section ids, nesting, layout attributes, and fills already in place.
2. Run pagx verify input.pagx to capture a baseline: fix any pre-existing diagnostics first (re-run until exit code is 0), then read input.layout.xml and input.png to see the current state.
3. Clarify the requested change with the user if the target, scope, or intent is unclear or ambiguous. Identify exactly which section id(s) the change touches.

Forbidden: Do NOT rewrite unrelated sections. Keep edits scoped to what the change requires.

Step 2: Make the edits

For each section being changed (identified by id), one at a time:

Do: Edit only the elements in this section. Preserve the existing structure, naming, and layout conventions unless the change requires altering them.

Checks:

1. Run pagx verify --scale 2 --id "sectionId" input.pagx — ALL diagnostics MUST be fixed. Re-run until exit code is 0 with no diagnostic output.
2. Read the section .layout.xml and verify element bounds match the intended change — check sizes (e.g., input height, icon dimensions), spacing, and that nothing has zero or unexpected dimensions. Fix any issues.
3. Read the section screenshot and verify the change landed as intended — check that colors, font sizes, text content, and icons are correct, and that nothing else in the section regressed. Fix any issues.

Cleanup: After all checks pass, delete that section's scoped artifacts (input.{id}.png, input.{id}.layout.xml) before moving on.

Forbidden: Do NOT edit sections the change does not require. Do NOT proceed to the next section until verify exits cleanly with zero diagnostics.

Step 3: Polish & QA

Do: Review the full design holistically and confirm the edits are consistent with the rest of the file — spacing, alignment, color consistency, visual hierarchy — and that nothing outside the intended change regressed.

Checks:

1. Run pagx verify --scale 2 input.pagx — ALL diagnostics MUST be fixed. Re-run until exit code is 0 with no diagnostic output.

2. Launch a sub-agent as an adversarial reviewer — this is the core of quality assurance. NEVER read references/checklist.md yourself; it is exclusively for the sub-agent. Use subagent_type="general-purpose" and model="reasoning". Use the following prompt, replacing placeholders with absolute paths:

   You are a strict, adversarial visual QA reviewer for a PAGX design file (an XML-based
   vector graphics format). Find every problem you can. Assume something is wrong until
   you prove it correct.
   
   Design intent: {design_intent}
   
   Files:
   - PAGX source: {pagx_path}
   - Layout XML: {layout_path}
   - Screenshot: {screenshot_path}
   
   Read all three files and {checklist_path}, then check every item in the
   checklist. Report every issue you find.
   

3. Copy every reported issue into the Polish task description as a numbered list. Work through each one: default to fixing; only mark [FALSE POSITIVE] if you can prove QA misread the file (e.g., layout.xml shows correct bounds). Do NOT dismiss issues as "minor", "looks okay", or "design constraint".

Final verification: After all fixes, run pagx verify one last time. If ANY diagnostic appears, the task is NOT complete — fix it. Only mark the task complete when verify exits with code 0 and produces no diagnostic output.

Keep final input.png for reference (do not commit). If further edits are made after this step, re-run the full verify to regenerate it. Delete input.layout.xml and any scoped {id} artifacts produced during the fix.

Live browser preview (required deliverable): do not auto-launch it. After the final pagx verify exits 0 with no diagnostics, the final reply MUST include the following block exactly, replacing the placeholder with the absolute path to the generated .pagx file. Never omit this block, even when pagx render has already produced a PNG:

需要交互预览（带热重载）可手动执行：
  pagx preview <需要预览的文件绝对路径>.pagx
或告诉我，我帮你启动。
运行 pagx preview stop 停止服务，pagx preview --help 查看更多。

Only start the daemon when the user explicitly asks to preview; then open the printed URL with the IDE's built-in browser tool (e.g. preview_url). The preview hot-reloads on save, so any later touch-ups refresh the open tab automatically. Stop the background daemon with pagx preview stop when done.

HTML to PAGX Workflow

Help regular users (no design-tool or PAGX experience) produce a PAGX file without writing PAGX by hand. The reliable path is two steps: design a beautiful, ordinary HTML page, then convert that HTML to PAGX with a single command. The converter renders the page in a real headless browser, so any modern HTML/CSS the design uses (flexbox, gradients, web fonts, Tailwind, inline SVG icons, charts on <canvas>) is flattened automatically into clean PAGX.

When: the goal is a finished PAGX and the user is approaching it visually — describes what they want in plain language ("一张活动海报", "a product card with price and button"), already has an .html file or a public URL to convert, or is a non-developer who should not be asked PAGX-specific questions. To modify an already-existing .pagx — precise PAGX semantics (constraints, repeaters, layer styles, animation-ready structure) or hand-editing XML — use the Update Workflow above instead; you can also hand a freshly converted .pagx off to it for deeper polish.

Communicate in the user's language. Mirror the language the user is writing in for all questions, explanations, and summaries. Keep the conversation non-technical — describe progress in terms of "the design" and "the PAGX file", not pipeline internals.

Step 0: One-time setup

Before the first conversion, make sure the tools are ready. There are two cases.

Case A — no repository (regular user, the common case). Install the published CLI as shown in CLI Setup above (npm install -g @libpag/pagx); the snapshot tool is bundled inside it. This stays light — the ~150 MB headless browser is not downloaded then. It installs itself automatically on the first conversion that needs it (Step 3), into a per-user cache, with progress shown on screen. Requires node on PATH.

Case B — inside the libpag repository (contributor). Build pagx from source and use it instead of the published npm package, so every conversion exercises local changes:

1. Build the CLI from source — produces cmake-build-debug/pagx:

   cmake --build cmake-build-debug --target pagx
   

2. Use it as pagx. Put the build directory on PATH for the session so every pagx … command below (and pagx verify) runs the local binary, then confirm it resolves:

   export PATH="$(git rev-parse --show-toplevel)/cmake-build-debug:$PATH"
   pagx -v
   

   (Alternatively call it by path as cmake-build-debug/pagx everywhere.)
3. Build the snapshot tool that pagx import shells out to when flattening HTML. The setup script installs its dependencies and builds it, then checks the headless browser is present (printing the exact install command if it is missing). With the repo-built pagx already on PATH from Step 2 it will not install the npm package. It runs on node, so the same command works on macOS / Linux / Windows:

   node .codebuddy/skills/pagx/scripts/setup.js
   

   Expected output ends with setup: ready. If it reports a missing headless browser, follow the exact install command it prints, then re-run it.

Skip this step on later runs unless a conversion fails with a setup-related error (see references/pipeline.md §Troubleshooting). Rebuild pagx (step 1) after any change to the CLI source.

Step 1: Understand the request

Ask only what is needed to design well, in plain language and in one short batch. Skip any question the user already answered or that has an obvious default.

• Purpose / kind: poster, card, banner, social post, slide, app screen, etc.
• Size: target width × height in pixels. If unknown, propose a sensible default for the kind (e.g. poster 1080×1440, card 640×400, banner 1200×400, story 1080×1920) and proceed.
• Content: the actual text (headings, body, labels, prices), and any logo/photo/icon. Ask the user to paste real text rather than guessing.
• Style: mood/colors/vibe ("clean and modern", "festive red and gold", "dark tech"). A reference image or brand color is ideal but optional.

If the input is already an .html file or a URL, skip straight to Step 3.

Step 2: Generate the HTML

Write one self-contained HTML file that renders the design exactly at the target size. Read references/authoring-html.md before writing — it lists the few rules that make the conversion clean (fixed canvas size, self-contained resources, icons as SVG, real text not pictures of text, what to avoid) plus design-quality tips.

Core rules to honor while writing:

• Set the canvas size on body, e.g. <body style="margin:0; width:1080px; height:1440px;">; the importer sizes the PAGX from that <body>. If a design larger than the default 1400×900 snapshot viewport comes out clipped, snapshot it with a matching viewport (Step 3, Custom viewport).
• Make it self-contained: inline images as data URIs or use absolute https:// URLs; pull web fonts via a Google Fonts <link>; do not rely on local relative files.
• Build the layout with normal CSS (flexbox, gradients, shadows, rounded corners). Use inline <svg> or an icon webfont for icons — never typed glyphs like +, ×, →.

Save it as <name>.html in the working directory (choose a short, descriptive <name>).

Step 3: Convert to PAGX

Inside the libpag repo (Case B): drive the conversion with the locally built pagx (Step 0) directly — no html2pagx wrapper. pagx import snapshots the page in a headless browser, imports it to PAGX, and resolves inline <svg>/import directives in one command (it auto-locates tools/html-snapshot/snapshot.js in the repo), so no separate pagx resolve is needed. pagx render then writes the preview PNG:

pagx import --input <name>.html --output <name>.pagx   # snapshot + import + resolve
pagx render <name>.pagx -o <name>.png                  # preview PNG; add --scale 2 for a crisp image

• Output: <name>.pagx (the result) and <name>.png (the preview render).
• A public URL works the same way (--input https://… --output <name>.pagx).
• Custom viewport / tall designs. pagx import snapshots at snapshot.js's default viewport (1400×900) and cannot be given a viewport directly. When a design needs a specific viewport (or comes out clipped), snapshot it separately with a matching --viewport-width/--viewport-height, then import the flat subset with the browser pass disabled — still only the local pagx, never html2pagx. See references/pipeline.md §Manual step-by-step pipeline.
• Fonts. This path does not embed the page's web fonts. If text renders in the wrong typeface, install that font on the machine, or embed it explicitly with pagx font embed --file <font> (see references/cli.md §pagx font). See references/pipeline.md §Fonts.

Expected: the commands print their progress and exit 0. Warnings about skipped/downgraded CSS are normal and usually harmless — pass -v to pagx import to see them (see references/pipeline.md). A hard failure or an empty/blank PNG means the design needs a fix (Step 4) or setup is incomplete (Step 0).

Installed via npm, no repo (Case A): the one-shot html2pagx wrapper is not on PATH, so run the built-in pipeline. pagx shells out to its bundled snapshot tool automatically (the first call triggers the one-time browser download). pagx import snapshots, imports, and resolves inline <svg>/import directives in one command, so no separate pagx resolve step is needed:

pagx import --input <name>.html --output <name>.pagx
pagx render <name>.pagx -o <name>.png   # preview PNG; add --scale 2 for a crisp image

A public URL works the same way (--input https://… --output <name>.pagx). Note: this path does not auto-embed web fonts — if text renders in the wrong typeface, either install that font on the machine, or embed it explicitly with pagx font embed --file <font>. See references/pipeline.md §Fonts.

See references/pipeline.md for advanced options (URL inputs, image storage modes, custom viewport via snapshot.js, and a manual step-by-step path for debugging).

Deliver the live browser preview command; do not auto-launch it. After Step 3 produces the .pagx, run pagx verify and fix every diagnostic until it exits 0 with no diagnostic output. Then the final reply MUST include the following block exactly, replacing the placeholder with the absolute path to the generated .pagx file. This is mandatory even when pagx render already produced a PNG:

需要交互预览（带热重载）可手动执行：
  pagx preview <需要预览的文件绝对路径>.pagx
或告诉我，我帮你启动。
运行 pagx preview stop 停止服务，pagx preview --help 查看更多。

When the user asks to preview, run pagx preview <absolute-path>.pagx, parse the printed URL, and open it with the IDE's built-in browser tool (e.g. preview_url). The PNG from pagx render is only for internal QA comparison and never substitutes for the mandatory interactive preview command delivered to the user.

Step 4: Review and iterate

1. Compare the <name>.png QA screenshot against the user's intent.
2. If something is wrong, edit the <name>.html (not the PAGX) and re-run Step 3. The HTML is the source of truth; treat the .pagx as a build artifact.
3. Common fixes:
   • Text in the wrong font → ensure the Google Fonts <link> is present; if the typeface is still wrong, install that font on the machine or embed it with pagx font embed --file <font>.
   • Content clipped or off-canvas → match --viewport-width/--viewport-height to the body size.
   • An element missing from the PNG → it was hidden, an unsupported widget, or a tainted <canvas>; see references/authoring-html.md §What to avoid and references/pipeline.md.
4. When the preview matches the intent, deliver <name>.pagx to the user and briefly describe what it contains. If a pagx preview daemon is running, stop it with pagx preview stop. Do not commit generated .png / .subset.html files.

For deeper polish of the resulting PAGX (precise spacing, constraints, animation-ready structure), switch to the Update Workflow, which edits the .pagx directly.

Live browser preview

pagx preview <file>.pagx starts a local HTTP server that renders the PAGX in a browser tab and watches the file for hot reload. Use it to let the user see the finished design interactively; use pagx render / pagx verify only for internal pixel-level QA screenshots (the sub-agent reviewer reads PNG files, not a live tab).

Treat the preview command as a required deliverable; do not auto-launch it. After generating a .pagx and completing a clean pagx verify, the final reply MUST include the following block exactly, replacing the placeholder with the absolute path to the generated .pagx. Never omit it, even when pagx render already produced a PNG:

需要交互预览（带热重载）可手动执行：
  pagx preview <需要预览的文件绝对路径>.pagx
或告诉我，我帮你启动。
运行 pagx preview stop 停止服务，pagx preview --help 查看更多。

Only start the daemon when the user explicitly asks to preview.

• Absolute paths. Prefer the absolute .pagx path in every command handed to the user because their shell may not be in the file's directory.
• Non-blocking. The default spawns a detached background daemon, prints pagx preview: http://127.0.0.1:<port>/... to stdout, and returns the shell prompt — it does not hang the session. In non-TTY / agent contexts no system browser is auto-opened; open the printed URL in the IDE's built-in browser instead (e.g. the preview_url tool).
• Hot reload. Saving the .pagx (or re-running pagx import in the HTML→PAGX workflow) refreshes every open tab automatically — start the preview once, then iterate and watch it update.
• Session reuse. Running pagx preview again reuses the running daemon for a new file; each file gets its own session, cleaned up independently when its tab closes.
• Always clean up. The daemon stays up until stopped. Run pagx preview stop when the user is done previewing to free the port and process.

See references/cli.md §pagx preview for all options (--port, --json, --foreground, etc.).

Delivery Contract (read last)

Before you end ANY PAGX task, your final reply MUST satisfy all of:

1. A .pagx that pagx verify exits 0 on — no diagnostics.
2. The exact, copy-ready pagx preview <absolute-path>.pagx command is shown to the user, using the mandated Chinese guidance block. This is a REQUIRED deliverable — never omit it, even when pagx verify / pagx render already passed.
3. The pagx render PNG was used only for your own QA comparison, never presented as the user's interactive preview.
4. (Update workflow) pagx verify final run exits 0 with zero diagnostics.

Failure mode — do NOT do this: spend the whole turn iterating on pagx verify until it passes, then reply without the preview guidance because you "already rendered a PNG". The PNG is internal QA; the preview command is the mandatory user deliverable.