Ship Nine Libraries at 1.0.0 With Hardened Versioning and Docs Shell

[AndrewRedican]

Description

Promotes nine libraries to their first stable 1.0.0 release, and does the work that release exposed: the versioning flow and the @hyperfrontend/package batch executor had several bugs that only surface on a repeat release against a populated registry, and the docs site needed to present a stable ecosystem rather than a flat list of packages.

Three threads run through this branch:

1. Versioning correctness. Release calculations now read the full commit range since the last release, refuse to publish when the registry cannot answer, refuse to move a version backwards, and realign a derived bump onto whatever is actually published. Pending file writes are flushed to disk before steps that shell out.
2. Batch release plumbing. The version-batch executor honours scope filtering, fails the batch when a library fails, detects dependents in every dependency section, and skips self-contained packages in the version cascade.
3. Docs site. Every documentation page now has a markdown counterpart served as plain text, a shared document shell with a floating index and copy/download actions, an ecosystem-ranked package hierarchy driving the landing page, and a build that fails on broken API source links.

Type of Change

🐛 Bug fix | ✨ Feature | 📝 Docs | 🔧 Build/Config

Changes Made

Stable releases

• Released 1.0.0 for logging, cryptography, network-protocol, string-utils, time-utils, json-utils, data-utils, function-utils, and immutable-api-utils, with changelogs and dependent version updates across the workspace.
• The changelog now announces a stable promotion explicitly instead of treating it as an ordinary minor bump.

Versioning flow (libs/versioning)

• Commit analysis reads the full range since the last release instead of a truncated window, and the git log range is bounded with a warning when it has to fall back.
• A repeat release is no longer reported as an initial release.
• New registry error model and npm error classifier: a failed registry lookup is now distinguished from a negative answer, and a release is refused when the registry cannot answer.
• Bump calculation refuses a version that moves backwards and realigns a derived bump onto the published version; a forced release starts from the published version.
• Added a disk-flush step to the flow executor, with requiresDiskFlush on step definitions, so steps that shell out (staging files for a commit) see the writes.

Package plugin (plugins/package)

• version-batch gained a scope option, applies scope filtering to batch runs, and fails the batch when any library fails to version.
• Dependent detection scans every dependency section, and the version cascade skips self-contained packages.

Release CI

• The main workflow preserves release tags when the registry cannot be reached, and fails loudly with the list of unverified tags rather than silently force-moving them.

Docs site

• Publishes a markdown counterpart for every doc page plus a machine-readable corpus generator, with vercel.json headers serving .md and llms.txt as plain text with CORS.
• New document shell: floating document index, markdown actions, decision record and markdown-backed pages rendered through it, and an agent documentation index linked from the footer.
• Landing page reorganised around an ecosystem hierarchy: packages ranked by their place in the hierarchy, highlights selected from it, the flagship promoted first, a koi pond accent theme, a lit band below the hero with the staged demo, and Utils packages listed by bare name.
• Navigation and anchors: subsections fold under the reader's current section, navigation stays reachable at every viewport width, heading anchors decode character references, and the scoped API reference is anchored and indexed.
• API source links point at the repository root, derive their repository URL from the workspace manifest, and the build fails on broken ones.

Roadmap and tooling

• Recorded versioning release-flow gaps, plus roadmap notes on releaseAs scope/prerelease reach and release rationale in changelogs.
• tool-media first-party dependencies pinned to published versions.

Testing

• New and updated unit specs in libs/versioning for bump calculation, changelog generation, registry fetch, npm error classification, and git log bounds.
• Docs site specs updated for the ecosystem ranking and the new landing highlights selection; the decision-engine spec dropped its non-null assertions.
• The nine 1.0.0 releases were exercised end to end through the batch release flow, and the package-e2e fixtures were updated to the published versions.

Screenshots/Videos

Visual surfaces worth a look when reviewing: the landing page hierarchy and hero band, the koi pond accent theme, and the document shell (floating index plus markdown actions) on any docs page.

Checklist

• I have performed a self-review of my code
• I have added/updated tests as needed
• I have updated relevant documentation
• I have used npm run commit for conventional commit messages

AI Assistance

Used Claude to make changes under close supervision.

Additional Notes

• Nine packages leave 0.x and enter 1.0.0. Their public APIs are unchanged by this PR; the version move is the semantic commitment, not a code break.
• The release flow is now fail-closed against the registry. If npm is unreachable, versioning and the tag-preservation CI step will stop rather than guess, which is a deliberate behaviour change for anyone running releases offline.

---

📝 CLA Requirement

By submitting this pull request, you acknowledge that:

• You have read and agree to sign our Contributor License Agreement (CLA)
• The CLA Assistant bot will automatically check your signature status
• If you haven't signed yet, the bot will provide instructions in the comments
• By signing, you grant the project maintainer exclusive rights to your contributions

For more information, see our Contributing Guide.

---

Thank you for contributing to hyperfrontend! 🚀

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs-site	Ready	Preview	Aug 31, 2026 5:35am

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 8e843fb

Command	Status	Duration	Result
nx run-many -t=e2e --projects=@hyperfrontend/wo...	✅ Succeeded	3m 39s	View ↗
nx run-many -t=build --projects=@hyperfrontend/...	✅ Succeeded	1h 6m 8s	View ↗
nx run-many -t=lint --projects=@hyperfrontend/w...	✅ Succeeded	2m 1s	View ↗
nx run-many -t=typecheck --projects=@hyperfront...	✅ Succeeded	1m 6s	View ↗
nx run-many -t=test --projects=@hyperfrontend/w...	✅ Succeeded	1m 4s	View ↗
nx version-check lib-time-utils	✅ Succeeded	1s	View ↗
nx version-check lib-json-utils	✅ Succeeded	1s	View ↗
nx version-check lib-string-utils	✅ Succeeded	1s	View ↗
Additional runs (16)	✅ Succeeded	...	View ↗

💡 Verify your cache is correct by running tasks in a sandbox. Read docs ↗

---

☁️ Nx Cloud last updated this comment at 2026-08-31 06:50:22 UTC