Release 4.0

[hexplus]

Release 4.0.0

Promotes the unreleased 4.0.0-rc.1 to the stable 4.0.0. No executable code changes — this is release preparation only: changelog, version, and README.

Why the changelog needed restructuring

4.0.0-rc.1 was never tagged or published (npm view sibujs still tops out at 3.4.1), yet CHANGELOG.md carried a dated ## [4.0.0-rc.1] — 2026-08-25 section and a separate 806-line [Unreleased] section holding PRs #51–#60. Both would ship in the same release, so a reader of the published changelog would have seen "Unreleased" describing work that was, in fact, released.

The two sections are now one ## [4.0.0] — 2026-08-28. Three further problems were fixed in the process:

• Duplicated category headings. [Unreleased] had accumulated ### Fixed ×3, ### Security ×2 and ### Changed ×2, because each PR appended its own block. Now one heading per category, with the #### <area> sub-heading style the rc.1 section already used, extended to 17 areas.
• The breaking-changes claim was false. The rc.1 preamble said "The only breaking change is the Node.js requirement" and "Beyond the engine floor there are no breaking changes." That stopped being true once [Unreleased] added a raised browser floor, a narrowed loadWasmModule() overload and a removed type field. ### Breaking now lists all four, and ### Migration to 4.0 is a numbered list covering each.
• New public types were undocumented. NavigationFailureReason, AsyncDerivedContext, ConflictStrategy and SyncConflict are named in the entries that already described their behaviour.

The merge was performed mechanically and verified: every content line from both sections appears in the result exactly once, with nothing dropped and nothing invented apart from the rewritten preamble and migration text.

Changes

File	Change
CHANGELOG.md	[Unreleased] + [4.0.0-rc.1] folded into one ## [4.0.0] — 2026-08-28; accurate ### Breaking and ### Migration to 4.0
package.json	4.0.0-rc.1 → 4.0.0
package-lock.json	version synced to 4.0.0
README.md	new ## Requirements section; malformed badge links fixed

The README stated neither of the release's two consumer-facing floors. It now declares Node ≥ 22.3.0 and Chrome/Edge ≥ 93, Firefox ≥ 92, Safari ≥ 15.4, matching engines.node and browserslist exactly. This matters because the README ships inside the tarball (files: ["dist", "README.md", "LICENSE"]), so it is the document consumers actually receive. The two badge lines were written [[text]](url) — the leftover of removing the image half of [![text](img)](url) — and rendered as literal brackets.

Review of v3.4.1 → 4.0.0

The full range (18 PRs, #43–#60) was audited for changelog coverage:

• Public API surface: 933 exported names vs 878 at v3.4.1 — 55 added, 0 removed. Of the 19 that are publicly reachable, 12 were already documented; 5 more are named by this PR.
• Subsystem coverage: every subsystem touched by those PRs is represented in the changelog.

Verification

All 15 certification gates pass on this tree:

Build · TypeScript (src) · Lint · TypeScript (tests+entries)          PASS
Full unit/integration suite            6276 tests (+1 skipped), 448 files
Public wrapper invariants 26 · Browser support floor 24               PASS
Query 6 · Router 7 · SSR security 8 fuzzing                           PASS
Browser matrix (Chromium/Firefox/WebKit)                       309 runs
Lifecycle + SSR soak                          25 tests (+1 skipped)
Packed package + subpath exports         157/157 checks, 16 subpaths
Bundler matrix (Vite/Rollup/esbuild/Webpack)  builds 12/12, runtime 12/12
Node support matrix              22.3.0:PASS  22:PASS  24:PASS

PASS: 15   FAIL: 0   NOT TESTED: 0

npm pack produces sibujs-4.0.0.tgz.

Known findings, not addressed here

Two internals are reachable from the public package, both new since v3.4.1:

Symbol	Reachable from	Its own JSDoc
__getNavigationEpoch	sibujs/plugins	"@internal Not part of the public API"
reportDrainRunaway	package root	"deliberately not a new public error API"

This is the same class of defect fixed for getRequestStore in #60. Because 4.0.0 is the first version to ship them to consumers, publishing converts them into semver commitments — removing them later would require a major. They are deliberately left out of the changelog so as not to document them as API. Fixing them before the tag costs nothing; afterwards it costs a major version.

Reviewer notes

• package-lock.json carries transitive dev-dependency bumps (brace-expansion, nanoid) beyond the version sync. These were written by scripts/certify/node-matrix.mjs, which runs npm install with cwd: REPO rather than npm ci. .gitignore documents (LOCK-001) that the lockfile is committed precisely to stop CI silently re-resolving transitive dev dependencies, so this is the drift that policy exists to prevent. Everything above was verified with these versions installed. Decide whether they belong in the release commit.
• test-results/ is not in .gitignore. It is Playwright's default outputDir and is rewritten on every browser run; on a failure it also collects traces and error-context.md. It was staged at one point during this work.

Not done

No tag, no publish, no dist committed.