Port Showcases

The React demo under packages/ag-charts-demos/src/demos/<demo>/ is the golden master. Each packages/ag-charts-demos/seeds/<demo>/<framework>/ port records in .seed-manifest.json the source hash it was last aligned to. This skill brings stale ports back into step and proves it.

Read first: packages/ag-charts-demos/tools/seeds/README.md (manifests, pins, the scripts), packages/ag-charts-demos/e2e/parity/README.md (the harness), .rulesync/rules/demo-ports.md, and for each port you touch, seeds/<demo>/<framework>.PORTING.md. Those are authoritative; this skill is the order of work.

Arguments

/port-showcases [demo] [framework] [--ci]

• demo (financial, web-analytics, procurement) and framework (angular, vue, typescript) filter the stale list; either may be given alone. Default: every stale port.
• --ci: headless run from .github/workflows/demo-port-align.yml. Commit, write the summary (step 5), and never push or open a PR; the workflow does both.

All commands run from the repository root with NX_DAEMON=false. Record the commit you start from as <base> (git rev-parse HEAD) before changing anything.

1. Find the stale ports and what moved

node packages/ag-charts-demos/tools/seeds/check-seeds.mjs --stale

Each entry names demo, framework, manifestCommit (last aligned) and sourceCommit (the golden master now). An empty list means nothing to do: say so and stop. For each entry, read the React change since the port was aligned:

git log --oneline <manifestCommit>..HEAD -- packages/ag-charts-demos/src/demos/<demo>
git diff <manifestCommit> HEAD -- packages/ag-charts-demos/src/demos/<demo> packages/ag-charts-demos/seeds/<demo>/react

The React seed diff also shows the files it vendors from sibling demos (the manifest's vendored list, such as web-analytics/topology.ts for procurement), whose changes make a port stale too. A manifest with no manifestCommit was never aligned: compare the whole port against React.

2. Port each change

Follow the port's PORTING guide: its file-mapping table, mapping rules and DOM invariants.

• Byte-identical modules are re-copied, never edited. Every file the mapping table marks as copied (data, types, formatters, CSS, vendored files) is copied again from the source the table names (the demo source, or the React seed for routes.ts and vendored/), then any rename the table lists is re-applied.
• Components and hooks are rewritten by the guide's mapping rules. Keep React's DOM, class names, roles, ARIA and data-* attributes: the functional specs and the pixel comparison key off them.
• Never edit src/demos/**, seeds/<demo>/react/** or anything outside the port to suit a port. If the port cannot match React without that, stop on that port and report why.
• Update the PORTING guide in the same commit when a mapping rule or invariant changed.

3. Restamp

Once a port reproduces the change:

node packages/ag-charts-demos/tools/seeds/stamp-port-manifest.mjs <demo> <framework>
node packages/ag-charts-demos/tools/seeds/check-seeds.mjs --stale --pins   # the port is no longer listed

check-seeds.mjs runs every check it is given and prints only the --stale report on stdout. Use the stamp script, not a hand-written manifest rewrite; it keeps vendored, dist and the pins. Never stamp a port that fails a gate below.

4. Gate

1. yarn nx run ag-charts-demos-seeds:build (every seed's typecheck and build; the React seeds included, so a broken golden master shows up here too).
2. Functional specs against each aligned port. Serve its dist and run the specs its guide names (the guides differ: -g <demo> or named spec files), from packages/ag-charts-demos: DEMOS_BASE_URL=http://localhost:<port> npx playwright test <selection>.
3. Pixel parity. Self-parity first, yarn nx test:e2e:parity ag-charts-demos, which must be pixel-identical. Then every aligned port as explicit targets in one run: serve each dist with node packages/ag-charts-demos/e2e/parity/serve-dist.mjs --dir <seed>/dist --port <port> and pass them all in PARITY_TARGETS (the parity README's "Explicit targets" subshell stops the servers on exit). Fix the port on a failure; never add a mask or widen the gate. The results are in packages/ag-charts-demos/e2e/parity/results/<run>/summary.json.
4. yarn nx format, then yarn nx format:check and yarn nx lint ag-charts-demos.
5. node tools/hot-paths/detect.js --range <base>...HEAD --summary.

Ports: the harness defaults to 4701 (reference), 4702 (self-parity copy) and 4710 upwards for served ports, and fails rather than reuse a busy one. Check each with lsof -nP -iTCP:<port> -sTCP:LISTEN first; move the reference and copy with PARITY_REFERENCE_PORT and PARITY_SELF_PORT and pick free ports for the seeds. Stop every server you started before finishing.

5. Output

• One commit per port: the port's files, its manifest and any guide change together, per /ag-eng:git-conventions. Use the ticket key when the work has one; a --ci run has none, so its subjects are plain, for example Align the financial Angular port with React at 1a2b3c4d.
• Interactive: stop at the commits; open a PR into the detected base (the release branch on one) only when asked, with /ag-eng:pr-create.
• --ci: also write reports/port-showcases/summary.md (gitignored), which the workflow puts in the PR body: a table of each port handled (demo/framework, the React commits ported, aligned or not and why), then each gate above with its verbatim result line. A port left stale must be listed with the reason. Never push, and leave no uncommitted changes other than .claude/settings.json.