Koi Motion Lib Consolidation and Frame-Death Recovery

[AndrewRedican]

Description

Lands the first two phases of the koi pond instance-model plan family (roadmap/showcase/16-koi-pond).

Phase 1 consolidates the roughly 78 percent of each fish app that was duplicated code into demo-koi-lib: a configurable steering brain, a shared runtime and renderer seam, the wire plumbing, the three.js stage, the identity-card anchor, and one copy of the fish chrome stylesheet. The koi inner contract moves to 0.8.0 to carry the shapes the instance model needs (identity.instance, pause.resting, and a predicted path on the outline).

Phase 2 ships the self-contained robustness fixes behind it. The features SDK gains a synchronous hosted signal so a feature opened directly can stop waiting on a host that will never answer, and page visibility is now reconciled rather than trusted: a missed visibilitychange edge used to park the watchdog at unobservable for the rest of the session. The same reconciliation lands in the pond host, alongside a device-pixel-ratio cap on every host-painted canvas, a device-tier shoal ceiling, and a gallery-side resurrection policy that heals a demo embed whose frame the browser killed instead of leaving the crash tile mounted.

Fish-app migration onto the consolidated lib, the dynamic shoal, and the overlay grammar are phases 3 to 5 and are not in this PR.

Type of Change

🐛 Bug fix | ✨ Feature | 📝 Docs | ♻️ Refactor | ⚡ Performance

Changes Made

• Koi steering brain (lib/src/motion): a configurable per-frame integrator with turn tiers chosen by obstacle proximity, flank selection read from the obstacle field, slowdown proportional to manoeuvre magnitude, and predicted advancement capped at 20 path points.
• Koi runtime and renderer seam (lib/src/runtime): one runtime every fish app drives, a renderer factory boundary, and a browsing-context reader; contract/wire.ts binds the contract to a runtime from a single place.
• Shared stage and chrome: a three.js koi-stage, the card-anchor clamp that parks every identity card, and styles/fish.css exported as ./fish.css with a build step and a pack-time export-target check in tools/refresh-lib.mjs.
• Geometry and model: describePondForFrame lets a frame be the whole world, koiVariantSeed seeds duplicates without re-rolling their species, and encounterClearance reports the clearance a pair of koi keeps.
• Koi contract 0.8.0: identity.instance, a resting hold on pause, and the committed path on outline; vendored lib tarball repacked.
• @hyperfrontend/features 0.8.0: hosted on the feature handle, and a shared watchPageVisibility (announcement as fast path, coarse poll plus a hidden-only probe frame behind it) now backing both the host and hostee visibility paths.
• Pond host: a visibility authority replacing the raw visibilitychange listener, canvasPixelRatio capping every host-painted canvas at two device pixels, and readDeviceProfile classifying capability signals into a shoal ceiling of 4 / 8 / 12.
• docs-site: createEmbedResurrection heals a killed demo embed with graced verdicts, backoff, an attempt cap, a stability window that restores the budget, and no reopen into a hidden page.
• Roadmap and findings: plan family 16 filed with phases 1 to 5, phases 1 and 2 collapsed into residue records, findings F-020 and F-021 registered, and the compose-independent-features guide repointed at the shared contract package.

Testing

Unit and browser suites added alongside every new module: the motion brain (including golden-trace and trajectory harnesses), manoeuvre selection, flight prediction, the koi runtime, browsing context, the three.js stage, wire binding, contract shape, virtual pond, card anchor, and traits in demo-koi-lib; device tier, pixel ratio, visibility, and the updated resurrection specs in the pond host; embed resurrection in docs-site; and page-visibility, lifecycle, frozen-lifecycle, and hosted browser specs in @hyperfrontend/features.

Device acceptance on physical hardware (the S24 Ultra frame-death case that motivated the phase 2 fixes) is tracked as a phase 5 work item and is not covered here.

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

Claude was used to generate code changes under supervision.

Additional Notes

• @hyperfrontend/features is released at 0.8.0 in this PR; hosted is additive on FeatureHandle, so anything implementing that interface directly (rather than consuming a handle) needs the new member.
• The koi inner contract bump to 0.8.0 is demo-internal. The fish apps still run against the previous shape and migrate in phase 3; the vendored demo-koi-lib tarball is repacked here so the new exports are available to them.
• The visibility reconciliation adds a 2s poll and, only while a page believes itself hidden, a probe animation frame. A genuinely hidden page is served no frames, so the probe costs nothing where battery matters.

---

📝 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 23, 2026 2:13am

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 5b134b4

Command	Status	Duration	Result
nx run-many -t=e2e --projects=demo-koi-fish-ang...	✅ Succeeded	1m 40s	View ↗
nx run-many -t=build --projects=demo-koi-fish-a...	✅ Succeeded	25m 43s	View ↗
nx run-many -t=typecheck --projects=demo-koi-fi...	✅ Succeeded	1m 42s	View ↗
nx run-many -t=lint --projects=demo-koi-fish-an...	✅ Succeeded	1m 42s	View ↗
nx run-many -t=test --projects=demo-koi-fish-an...	✅ Succeeded	1m 16s	View ↗
nx run-many -t=format:check --projects=demo-koi...	✅ Succeeded	<1s	View ↗
nx version-check lib-features	✅ Succeeded	<1s	View ↗

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

---

☁️ Nx Cloud last updated this comment at 2026-08-23 02:46:19 UTC