2026 OpenClaw Frontend Practice on a Remote Mac: Unlighthouse JSON, Dead-Link Thresholds, and Lighthouse PR Summary — Reproducible Steps
Audience: frontend CI on a remote Mac that must parse Unlighthouse JSON, enforce 4xx budgets, and post Lighthouse digests to the PR. You get matrices, field notes, thresholds, and steps for OpenClaw—plus links to preview webhook and Bugsnag Lighthouse PR summary.
Single-url Lighthouse misses sitemap 404s and cross-page dead anchors. Outcome: Unlighthouse plus Lighthouse on Apple Silicon, merged by OpenClaw into one sub-4 KB PR comment.
Pain points this pipeline removes
1) Lighthouse on / only while nested docs 404.
2) Dead-link failures stay in logs, not PR comments reviewers read.
3) Container Chromium diverges from the Mac that runs Safari smoke.
Unlighthouse vs single Lighthouse CLI: which gate when
Use both, but never interchange their verdicts. Unlighthouse answers site-wide crawl health; Lighthouse answers lab performance on a short allowlist.
| Tool | Best for | Skip when |
|---|---|---|
| Unlighthouse CI | Internal link graph, status codes per route, sitemap discovery on preview hosts. | You only ship a single-page app with no marketing routes. |
| Lighthouse CLI | LCP, CLS, TBT budgets on checkout, home, and pricing URLs after warm-up. | You need proof that blog posts three levels deep still resolve. |
| Combined OpenClaw gate | One Markdown digest: broken links first, worst metric second, exit code maps to merge policy. | You have not pinned Chrome and Node majors on the same Mac worker. |
Install Node 24+ and OpenClaw gateway on the remote Mac
- Pin Node 24 LTS with the same major in CI metadata; enable
corepackfor pnpm. - Install OpenClaw CLI globally or via repo devDependency; store
OPENCLAW_GATEWAY_TOKENin macOS keychain, not the repo. - Expose HTTPS ingress on the leased host; verify HMAC on deploy webhooks per the preview webhook HowTo.
- Queue jobs locally under
.openclaw/queue/so SSH blips do not drop crawls mid-run. - Pin Chromium to the same build Unlighthouse and Lighthouse share; record the path in
.openclaw/toolchain.lock.json.
node -v # expect v24.x pnpm add -D @unlighthouse/cli lighthouse openclaw openclaw gateway doctor --json > .openclaw/reports/doctor.json
Unlighthouse CI output JSON: fields your parser must read
Run with --reporter json and write .openclaw/reports/unlighthouse.json. Stable keys matter more than pretty printing.
- site.url — canonical preview root; compare to
PREVIEW_URLfrom the hook. - routes[] —
path,score, optionalreports.lighthouse. - reports.links — filter
status >= 400on internal hrefs. - summary.brokenLinks and ci.buildId — fast fail and
OPENCLAW_RUN_IDcorrelation.
Dead links, 4xx ratio, and merge block rules
| Signal | Budget | Exit code |
|---|---|---|
| Broken internal links | 0 on release branches; <= 2 on long-lived docs branches with ticket IDs in PR body. |
2 regression |
| 4xx rate on crawled internals | <= 0.5% of internal hrefs (min sample 200 links). |
2 when exceeded |
| 5xx or timeout | Any route >= 500 on allowlisted paths blocks merge. |
3 after one retry (infra) |
Performance regression thresholds (LCP, CLS, TBT)
Run Lighthouse on three revenue URLs; compare perf/thresholds.json at the same SHA.
| Metric | Mobile budget | Fail action |
|---|---|---|
| Performance score | >= 0.85 |
List delta vs baseline artifact in PR comment. |
| LCP | <= 2500 ms |
Cite worst URL first; attach lhr.json path. |
| CLS | <= 0.08 |
Block when hero layout shifts after font swap. |
| TBT | <= 200 ms |
Exit 2; cite worst URL. |
OpenClaw aggregate report: PR comment and webhook upsert
- Merge
link_gate.jsonandlhr.jsonsummaries intogate_digest.json. - Render
pr_unlighthouse_lighthouse.mdfrom template; keep under 4 KB for mobile reviewers. - PR comment: PATCH bot comment with HTML marker
<!-- openclaw-unlh-lh -->; same flow as Playwright JUnit PR summary. - Webhook: POST digest to OpenClaw
/v1/runs/{id}/eventsfor Slack or deployment rows.
Safari and WebKit coordination on the same Mac
Chromium lab scores do not replace WebKit. After the gate, run the dual Safari Playwright matrix with --workers=1. Fail merge only when webkitBlocksMerge: true in policy JSON.
Common errors FAQ
Unlighthouse reports zero routes
Check protocol on site.url, enable sitemap discovery, and pass preview auth headers if the host sits behind SSO.
Dead-link counts differ between CI and the Mac
Run both crawls on the same region and DNS resolver. Mount the same cookie jar file OpenClaw uses for authenticated previews.
Lighthouse passes but PR still shows fail
Link gate may have exited 2 first. Sort the digest with broken links before performance lines.
Citable thresholds for architecture reviews
Cap Unlighthouse routes at 150 on preview hosts to finish within 12 minutes on M-class nodes.
Require at least 200 internal hrefs before enforcing a 0.5% four-xx ratio.
Keep merged PR comments under 4096 bytes; truncate route lists to 10 rows with a link to artifacts.
Lease a remote Mac frontend build node when you want Unlighthouse, Lighthouse, and Safari lanes on one Apple Silicon host. Compare node packages, read SSH and VNC access, browse the blog index, and plan capacity on home.
Choose nodes for Unlighthouse and Lighthouse lanes
Run Unlighthouse crawls and Lighthouse budgets beside Playwright Safari on leased Apple Silicon. Continue with Playwright HTML report PR summary, then open Mac Mini M4 packages.