Add a build-time opt-in hybrid API documentation POC

[David Pine (IEvangelist)]

Summary

Adds a local POC for building only non-API documentation statically, while rendering C# and TypeScript API reference HTML and Markdown on demand through the existing ASP.NET Core StaticHost.

• Build-time opt-in: ASPIRE_HYBRID_API_DOCS=1, with cross-platform build:hybrid and build:hybrid:skip-search commands. The default build remains fully static, including API docs.
• Existing public host: StaticHost serves the selected static client and calls a private, long-lived Astro/Node worker on API cache misses. Uses the official Node adapter rather than reimplementing Astro rendering in .NET.
• Bounded origin caching: process-local ASP.NET output cache, 128 MiB capacity, 30-minute expiration, 64 MiB maximum renderer response, build/URL/representation-aware keys, and request coalescing. Buffers complete responses before sending an exact Content-Length; excludes failed, private, authenticated, and cookie-setting responses.
• Route compatibility: shares request-time lookups with existing slug/overload rules; preserves Markdown aliases, canonicalization, negotiated Markdown headers, alternate links, configured redirects, API search, and sitemap discovery. Restricts runtime image rendering to bundled local images with bounded dimensions.
• Artifact and local-run isolation: separate dist-hybrid client/server output, private manifest with build identity and platform checks, and opt-in Aspire wiring. Builds matching Linux and Windows artifacts; rejects mismatched host/artifact modes instead of silently falling back.
• Opt-in verification: dedicated CI compares both build modes, checks emitted files rather than only route flags, and exercises the real built host, cache behavior, Markdown, browser navigation, images, and renderer outages. Contributor instructions cover artifact retrieval and local usage.

This is intentionally local-only. Azure hybrid publishing, Front Door configuration changes, Redis-backed output caching, and distributed locking are not included. Existing Redis usage for live status and the default Azure/static deployment path are unchanged.

Measured POC result

The successful acceptance run compared both modes at this PR's head commit:

Measurement	Fully static	Hybrid
Build duration	21m 16.54s	13m 51.82s
Client output	8,588,160,446 bytes	3,141,498,206 bytes
Client files	68,819	20,517
Peak build RSS	Approximately 5.2 GiB	Approximately 8.4 GiB

The hybrid build avoided 48,451 API HTML/Markdown files, preserved 8,828 non-API HTML/Markdown outputs, and produced a private server bundle of 123,244,200 bytes. The faster build and smaller client output come with higher peak build memory in this run; this is not a claim that hybrid mode lowers memory usage or is production-ready.

Third-party links and affiliations

None. This change does not add or change third-party links.

Validation

Opt-in CI passed on d0476d4737a0c813d31b33ec9818f37fd23a0963, including Linux acceptance verification and the Windows artifact/contracts job. Exact commands below were run from src/frontend in CI:

• pnpm exec astro sync — passed.
• pnpm exec eslint . --max-warnings 0 — passed.
• pnpm exec vitest run --config vitest.config.ts tests/unit/hybrid-api-docs.vitest.test.ts tests/unit/api-markdown.vitest.test.ts tests/unit/ts-api-route-catalog.vitest.test.ts tests/unit/build-performance.vitest.test.ts — passed.
• dotnet test ../../tests/StaticHost.Tests/StaticHost.Tests.csproj --filter 'FullyQualifiedName~HybridApiDocs' --nologo — passed on Linux and Windows.
• dotnet test ../../tests/Aspire.Dev.AppHost.Tests/Aspire.Dev.AppHost.Tests.csproj --filter 'FullyQualifiedName~HybridApiDocs' --nologo — passed.
• pnpm build:production with the toggle unset — passed; static baseline retained API output.
• pnpm build:production with ASPIRE_HYBRID_API_DOCS=1 — passed on Linux and Windows.
• node scripts/verify-hybrid-output.mjs — passed; zero static API HTML/Markdown, non-API inventory parity, redirect destinations, private server separation, and API sitemap coverage.
• dotnet build ../statichost/StaticHost/StaticHost.csproj -c Release --nologo with the toggle enabled — passed.
• node scripts/test-hybrid-host.mjs with HYBRID_TEST_BROWSER=1 — passed, including pnpm exec playwright test --config playwright.hybrid.config.mjs, twenty concurrent cold requests coalesced into one render, large-response lengths, representation isolation, and static/warmed-cache availability after stopping the worker.

Also verified locally using the Windows CI-built artifact and an isolated Aspire AppHost: the real homepage, API rendering/cache hits, Markdown copy actions, completed client-side navigation, lazy-loaded images, and bounded gateway errors for cold requests during a worker outage. No full-site build was run locally, and transient services were stopped.

Limitations: Azure deployment, Front Door behavior, and distributed caching were not tested. The full viewport suite was not rerun on the final commit; an earlier broad run reported ten mobile Developer Hub failures outside the focused POC coverage. The raw repository-wide tsc --noEmit check also reports existing unrelated diagnostics; no diagnostics remained in the new hybrid code.

[aspire-repo-bot]

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #1874. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

This comment updates automatically when a new frontend build artifact is uploaded.