skills.rest
vchelaru
vchelaruCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

html-to-gum-fidelity

Iterates HTML-to-Gum conversion against pixel-diff gates to improve site rendering fidelity.

614|78|Updated Mar 11, 2015
Search Tags:#regression testing#playwright#font rendering#visual fidelity#pixel diff#HTML conversion#gum ui
One-click install
npx skills add https://github.com/vchelaru/Gum --skill html-to-gum-fidelity
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: html-to-gum-fidelity
Source: https://github.com/vchelaru/Gum/tree/main/.claude/skills/html-to-gum-fidelity
Command: npx skills add https://github.com/vchelaru/Gum --skill html-to-gum-fidelity

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Converting live websites into Gum UI layouts often produces visual mismatches — font rendering gaps, misrasterized SVGs, broken backgrounds, and rotating carousels — that are hard to diagnose without a structured pixel-comparison loop. This Skill provides the site-fidelity workflow for running the HtmlToGum converter, measuring pixel diffs against Chromium screenshots, and applying focused converter fixes.

Core Features & Use Cases

  • Pixel-gate fidelity loop: Run npm run site-fidelity -- <url> to convert a page, capture Chromium and Gum screenshots, and score the percentage of mismatched pixels.
  • Known-landmine catalog: Documents dozens of diagnosed converter issues (custom-font wrapping, icon-font pseudos, transparent SVG isolation, Google Fonts unicode-range subsets, negative z-index ordering) so fixes target real root causes.
  • Rotating-media stabilization: Uses stabilizeDynamicMedia to freeze carousels, cookie banners, and animations before extraction so diffs measure layout, not timing.
  • Canary regression suite: Run npm run canaries -- --tier=local after every converter edit and --tier=live before committing to catch regressions against checked-in baselines.
  • Use Case: A developer converts pocket.com to Gum and sees a 12% pixel miss; the Skill directs them to check custom-font multi-line paragraph rasterization and FontCache atlas contents before touching layout code.

Quick Start

Run the site-fidelity harness on a target URL with a pixel threshold, then diagnose the top diff regions and apply one focused converter fix before re-running.

Frequently Asked Questions about html-to-gum-fidelity

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run the HtmlToGum site-fidelity check on a website?▼

Run `npm run site-fidelity -- <url> --max-pages=1 --max-pct=5` from either the Tool/HtmlToGum/converter or Tool/HtmlToGum/fidelity directory. Outputs land in Tool/HtmlToGum/.site-fidelity/<slug>/ with diff regions to diagnose.

Why does converted text render wrong with custom web fonts?▼

BitmapFont wrapping differs from Chromium for custom faces, and Google Fonts unicode-range subsets can bake a Cyrillic-only TTF producing empty atlases. Check FontCache .fnt files for chars count, prefer faces covering basic Latin, and raster multi-line custom-font text blocks.

How do I handle rotating carousels causing pixel diff failures?▼

The stabilizeDynamicMedia step already pins carousels, pauses CSS animations, and clears timers before extraction. If capture-meta.json shows suspectedRotatingMedia: true, do not write probe scripts — fix mapping or fonts, or move to the next site after one re-run.

Why does the converted page show a transparent background instead of white?▼

Browsers paint the page canvas white by default but Gum has no such default, leaving the root transparent. The converter propagates the effective page background onto the root body/html node so BodyBg paints a backmost fill.

What regression tests should run after editing the HtmlToGum converter?▼

Run `npm run canaries -- --tier=local` after every fix and `--tier=live` before committing. The gate fails if any entry exceeds maxPct or rises more than maxDeltaPct above its checked-in baselinePct in canaries.json.

When should I stop iterating on a failing site's fidelity?▼

Stop after one focused converter patch and re-run per site. If the same rotating-media or hash-routing hypothesis still fails after stabilization ran, abandon that hypothesis and move to the next site rather than spending more iterations.

Related Skills

Explore More Software Engineering Skills→
Gekkos-techGekkos-tech
4

image-to-code

Convert design images into websites with layout, spacing, color, and typography analysis.

Official
Advanced
vchelaruvchelaru
597

gum-cli

Create, validate, and generate code for Gum projects via headless CLI.

Community
Advanced
vchelaruvchelaru
597

gum-runtime-fonts

Guide font loading and management across Gum's three runtime paths.

Community
Intermediate
vchelaruvchelaru
597

gum-tool-selection

Explain Gum editor selection with input handlers, marquee selection, and locked instances.

Community
Advanced