docs(perf): add list virtualization implementation plan and perf fixtures

[robert-hebel-sb]

Description

Adds planning documents for virtualizing Swagger UI's large-list rendering paths, plus the generated OpenAPI fixtures the future E2E tests will need. No production code changes — this is documentation and test fixtures only.

Three phases, each targeting a list that currently renders in full regardless of viewport:

Phase	Target	Complexity
1	Models/schemas list (json-schema-5)	Medium
2	The self-contained oas31 models copy	Low–Medium
3	Operations list	High

Each phase virtualizes only above an item-count threshold, so specs below it keep today's markup, DOM structure and find-in-page behaviour unchanged. That is what keeps the existing Cypress and Selenium selectors valid without edits — at the cost of maintaining two render paths per component, which the docs call out explicitly.

Motivation and Context

Large specs (Kubernetes, GitHub, AWS) carry 500–1000+ operations and 200–800+ schemas, and today every one of them mounts on load. The result is slow first paint, high memory use, and sluggish expand/collapse.

The documents exist to front-load the findings that are easy to get wrong during implementation. Several were verified against the code and contradict the obvious assumption:

• Collapsed operations and models already unmount their subtrees (Collapse returns <noscript/>; ModelCollapse renders { expanded && children }). So the win is in row count, not subtree depth — the expected gain is smaller than "800 full schema trees → 15" would suggest, and the docs size it accordingly.
• Model deep-linking does not exist. isShownKeyFromUrlHashArray only ever emits ["operations", …] keys, so the readyToScroll calls in models.jsx are dead code. An earlier draft treated this as a blocking risk; it isn't.
• Virtual items need content-derived getItemKey values, with the tag included for operations — an operation under two tags renders twice, and index keys would let component state (an open try-it-out panel) follow the wrong row.

Virtualizing schema property lists was considered and rejected (recursive rendering vs. TanStack's flat-list requirement); the reasoning is recorded in the README so it doesn't get re-litigated.

How Has This Been Tested?

Not applicable — no code changes. The fixtures were validated as parseable and their counts checked programmatically:

• many-schemas.swagger.yaml / many-schemas.openapi.yaml — 240 schemas each
• many-schemas.openapi31.yaml — 240 schemas, openapi: 3.1.0 (routes to the oas31 component, not json-schema-5)
• many-operations.yaml — 529 operations across 24 tags, and includes a two-tag operation covering the duplicate-key case

All are sized deliberately above the proposed thresholds, so the virtualized path is actually exercised rather than silently falling back to the legacy one.

Notes for reviewers

• The plans live under .claude/implementation/ rather than docs/, to keep them out of the published GitBook.
• Fixtures are generated; each carries a "regenerate rather than hand-edit" header pointing at its phase document.
• Two numbers are deliberately left as labelled placeholders (estimateSize, and the perf baselines) because they need measuring on a real machine rather than guessing.

Checklist

• No code changes (documentation and test fixtures only)
• No breaking changes
• Documentation added
• Tests added — not applicable; fixtures land here, tests arrive with each phase

🤖 Generated with Claude Code

[swagger-bot]

🎉 This PR is included in version 5.32.13 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀