feat: tick-rate mount contract — ui.__tickHz handshake, rebuilt xcframework (0.2.1)

[NathanWalker]

Prep for 0.2.1 — the tick-rate release owed since 0.2.0 shipped ahead of the engine-side review (see RELEASE-PLAN-0.2.1.md, updated on this branch). The contract is now settled on pocket-stack/pocketjs#257 (head d6ae5f0): the rate is declared before eval_bundle, published to the guest at mount as ui.__tickHz, and every bundle refuses a host driving a rate other than its baked one.

What changed

• PocketHostView._mountUi publishes __tickHz next to __host/__hostAbi — external-guest mode's half of the pairing handshake. The value is read from the surface's accepted rate, so it is always what the core actually runs.
• tickRate gained a setNative: same-value re-application (property application after createNativeView already declared the rate) is skipped; a genuinely late change is pushed so the new surface refuses it through the error event instead of the display link silently diverging from the realm's step.
• Rebuilt PocketApple.xcframework from the #257 head: call order create → load_pak* → [set_identity] → [set_tick_rate] → eval_bundle, PocketSurfaceView applies tickRate in its setter (start only pins the display link), and the embedded surface publishes __tickHz for PocketView's guest mode.
• README (usage, identity handshake, provenance now citing #257) and index.d.ts contract text; version 0.2.1.

Compatibility

60 Hz bundles mount on every plugin version — an absent __tickHz means the 60 default, which is all any pre-rate host ever drove. Non-60 bundles refuse 0.2.0 loudly (nothing in it declares a rate) and require this release.

Validation (iPhone 17 Pro Max simulator, iOS 26.5)

• Guest mode: pocket ios play nsengine --hz=120 --density=4 --plugin-path=<this checkout> — [pocket-shell] guest loaded, nsengine renders fully, spinner animating, guest↔host ping round-trip live (screenshot-verified).
• External-guest mode: pocket ios play nsengine --external-guest --no-build --plugin-path=<this checkout> — the new build stamp staged tickHz: 120 with no --hz flag (previously this silently staged 60), and the bundle mounted against the plugin-published __tickHz.
• npm pack ships 18 files / 2.7 MB; both xcframework slices carry the new pocket_apple.h contract and PocketSurfaceView.h setter docs.

Before publishing (do not merge until then)

1. feat(core): per-realm tick rate — fixed-step at a declared hz pocket-stack/pocketjs#257 merges (then #258).
2. Rebuild the xcframework from post-merge main and re-vendor — the binary here is a build of the branch head, kept so this PR is testable end-to-end; the shipped one must be a build of upstream.
3. npm publish, then the one-line ns-shell pin bump (0.2.0 → 0.2.1) upstream.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 475315f8-77bc-4c42-8b4e-8c03d238da7e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}