mp-groundline

Migrate a WeChat Mini Program off the Skyline renderer onto the WebView renderer while keeping the front-end visually and behaviorally consistent, and hand the next agent a MIGRATION-MAP debug doc that maps what changed.

Prime directive — minimal diff, consistency first

The renderer flip (app.json renderer: "skyline" → "webview") is the one change that does ~90% of the migration. Everything else is conservative.

A mature Skyline program is full of workarounds — patterns the team adopted to cope with Skyline's stricter subset (box-shadow used as a border, flex+width instead of CSS grid, word-break: break-all, scroll-view type="list"/"custom", precomputed template flags, a tap-mask over <camera>). These all still render under WebView. So the consistency-preserving move is to KEEP them, flip the renderer, then verify each page and fix only the deltas that actually appear. Reverting a workaround "because WebView now supports the native feature" is the opposite of consistency and is OUT of scope unless the user asks to modernize.

Hard Skyline-only features (worklet animations, custom routes, Skyline-exclusive components) have no WebView equivalent and DO require a real rewrite — but only when the scan finds them. Flag, never silently drop.

What this skill produces

1. A migration scan (deterministic JSON) — renderer_config + a categorized inventory of every Skyline-specific usage / workaround, each tagged mechanical / keep / verify / rewrite.
2. The MIGRATION-MAP.md debug doc (the headline deliverable) — config diff, the general Skyline↔WebView element/API table, the rewrite manual-review gate, and one row per finding (file:line + action + debug note).
3. The migrated program — renderer flipped, workarounds kept, real deltas fixed minimally, each fix re-verified.

Steps

Preflight

Resolve miniprogramRoot; locate app.json; confirm Skyline — app or any page json renderer: "skyline". Confirm a clean git tree so the flip is revertible.

Step 1 — Scan → load rules/scan-protocol.md

node scripts/scan.mjs <program-root>

Emits renderer_config + findings[] + summary. Every rewrite finding is a manual-review item surfaced up front. If summary.already_migrated (app and every page on WebView) → report it, keep the scan as inventory, STOP before editing.

Step 2 — Emit the MIGRATION-MAP (doc-before-edit gate)

node scripts/gen_migration_map.mjs <program-root>   # or pipe the scan JSON

Write MIGRATION-MAP.md before any edit so the plan is reviewable. Contract: references/scanner-contract.md; mapping evidence: references/skyline-to-webview.md.

Step 3 — Mechanical flip

renderer → "webview" in app.json (only if it says skyline) and in every page_renderer_override page json (the app flip does not reach a Skyline pin). Keep glass-easel, style:"v2", navigationStyle:"custom", lazyCodeLoading, per-page disableScroll; keep or strip rendererOptions.skyline (ignored by WebView) — without its defaultDisplayBlock/defaultContentBox, every page that ran on Skyline shifts layout (flex + border-box defaults; only the pinned pages under per-page adoption; references/skyline-to-webview.md).

Step 4 — Verify → load rules/verify-with-vince-mp.md

Use the system vince-mp CLI (the tool mp-cli-sup drives — do NOT rebuild it) to capture before/after screenshots + pageData per page and diff → the list of actual deltas. Precondition (check it before Step 3 — the baseline is captured pre-flip): vince-mp session start --json returns ok (vince-mp on PATH + a reachable DevTools automation port). If it cannot run: keep the flip uncommitted (revertible), mark every page UNVERIFIED in the MIGRATION-MAP, make no Step 5 fixes, and tell the user to run Step 4 — no verification → UNVERIFIED, not consistent.

Step 5 — Targeted fixes → load rules/minimal-fix-protocol.md

Fix ONLY confirmed deltas, smallest change first, re-verify each. Record each fix in the MIGRATION-MAP.

Step 6 — Finalize

Update the MIGRATION-MAP with applied fixes + remaining rewrite items. Report diff size (files touched, lines changed) — minimal is the goal. Rollback = git checkout of app.json + touched page .json.

Scope boundary

• IN: Skyline→WebView migration of a WeChat mini program; consistency-first minimal-diff edits; the deterministic scan + MIGRATION-MAP doc.
• OUT (route elsewhere): live runtime debugging → mp-cli-sup; DEVELOPING Skyline components / worklet animations / custom routes → the skyline-* skills (opposite direction); webview→skyline reverse migration; perf-only optimization with no renderer change; modernizing/reverting a workaround unless explicitly asked; non-WeChat work. The discriminator is DIRECTION (off Skyline) + INTENT (migrate+consistency, not develop/debug/optimize).

Metrics

Three success metrics — migration_correctness, minimal_diff, activation_precision — with full definitions, oracles, targets, and measured values in assets/metric-plan.json. Load it when validating or releasing.

Modules (load on demand)

Scripts

Assets