Fit zoom clamp: small graphs no longer balloon

[aaltshuler]

Second half of the first-load-feel work. Measured on the sweep protocol: a 60-node graph fit at zoom 4.3, 300 nodes at 3.3 — small graphs zoom until nodes are balloons.

• FitViewOptions gains maxZoom; CosmosEngine honors it by centering the scene bbox at the bound with one animated transform when the natural fit would exceed it (native fit otherwise; headless containers and unknown positions fall back).
• Core threads a new fitViewMaxZoom construction option (default 1.5, null disables) through every internally issued fit: first-data fit, settle follow, public fitView.
• React exposes the prop.

Verified live on the same fixtures: small-graph fits land at exactly 1.5 (previously 3.1–4.3), nodes at natural scale. 4 new adapter tests + 1 core threading test; two existing fit-args assertions updated. Full check green (1,798 tests).

🤖 Generated with Claude Code

https://claude.ai/code/session_018SeFxK217ZrHSERqK6kjcb

Greptile Summary

The PR adds a configurable maximum zoom for fit operations, defaulting to 1.5 and allowing null to disable the clamp.

• Extends the engine fit contract with maxZoom.
• Threads the construction option through first-data, settle-follow, and public core fit operations and exposes it through React.
• Implements clamped bounding-box centering in the Cosmos adapter, with native-fit fallbacks for unavailable geometry or containers.
• Adds adapter and core coverage for default, custom, disabled, bounded, and fallback behavior.

Confidence Score: 5/5

The PR appears safe to merge with no concrete correctness or security failures identified.

The fit bound is consistently threaded through the public layers, and the Cosmos adapter retains native fallback behavior when clamped fitting cannot be safely computed.

Important Files Changed

Filename	Overview
packages/core/src/engine/index.ts	Extends the engine-neutral fit contract with an optional maximum zoom.
packages/core/src/instance.ts	Applies the configured clamp consistently to first-data, settle-follow, and public fit operations.
packages/engine-cosmos/src/CosmosEngine.ts	Adds finite positive zoom-bound handling and a point-bbox-based clamped camera transform with native fallbacks.
packages/react/src/Graph.tsx	Exposes the construction-only fitViewMaxZoom option and forwards it during instance creation.
packages/engine-cosmos/test/cosmos-engine.test.ts	Covers bounded small scenes, native fallback, degenerate single-point scenes, and headless containers.
packages/core/test/settle-camera.test.ts	Verifies default, disabled, and custom zoom clamps on internally issued fits.

Sequence Diagram

sequenceDiagram
    participant App as React/Application
    participant Core as GraphInstance
    participant Adapter as CosmosEngine
    participant Cosmos as Cosmos Graph
    App->>Core: Construct with fitViewMaxZoom
    Core->>Adapter: "fitView({ maxZoom, durationMs? })"
    Adapter->>Cosmos: Read point positions
    alt Natural fit exceeds maxZoom
        Adapter->>Cosmos: Center bbox at maxZoom
    else Fit is within bound or geometry unavailable
        Adapter->>Cosmos: Native fitView
    end

Loading

_{Reviews (1): Last reviewed commit: "Fit zoom clamp: small graphs no longer b..." | Re-trigger Greptile}