First pass on 'headless' version of SpatialCanvas component with some notes on future design

[xinaesthete]

Summary by CodeRabbit

• New Features

  • SpatialCanvasViewer: New component for rendering spatial data with support for custom deck.gl layers, automatic view framing, and hover tooltips.
  • SpatialViewer now accepts custom deck.gl configuration options via deckProps.

• Documentation

  • Updated MDV integration documentation with architecture and phased context details.
  • Added MDV release checklist for package shipping readiness.

[coderabbitai]

Warning

Rate limit exceeded

@xinaesthete has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 28 minutes and 40 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 4fbe7d46-a5ec-48e2-b1da-2d880d097633

📥 Commits

Reviewing files that changed from the base of the PR and between 2dc6ec6 and cfde70e.

📒 Files selected for processing (5)

• docs/docs/vis/mdv-integration.mdx
• docs/docs/vis/mdv-release-checklist.mdx
• packages/vis/src/Sketch/demoUrl.ts
• packages/vis/src/Sketch/index.tsx
• packages/vis/tests/demoUrl.spec.ts

📝 Walkthrough

Walkthrough

This PR introduces the "bridge path" implementation for MDV integration: a new headless SpatialCanvasViewer component that reuses existing Viv/deck rendering while accepting caller-provided Deck.gl layers. SpatialViewer gains support for external deckProps, SpatialCanvas refactors to use a new renderer hook for state management, and all new utilities are exposed via the public API with supporting tests.

Changes

MDV Bridge Path Integration

Layer / File(s)	Summary
Architecture & Release Readiness Documentation docs/docs/vis/mdv-integration.mdx, docs/docs/vis/mdv-release-checklist.mdx	MDV integration guide now clarifies the "bridge path" approach with a public headless SpatialCanvasViewer that reuses Viv/deck rendering. New release checklist defines scope (Viv as raster foundation), integration contracts (MDV-controlled state composition), and release criteria across API, parity, versioning, and non-goals.
SpatialCanvasViewer Headless Component packages/vis/src/SpatialCanvas/SpatialCanvasViewer.tsx	Adds SpatialCanvasViewer React component with useSpatialCanvasRenderer hook that derives deck/viv layers via useLayerData, composes external layers above generated ones, computes enabled-layer state and auto-fit bounds, and returns aggregated rendering state. Component measures container, manages hover tooltips via React portal, and renders loading/placeholder states. Wraps inner implementation with VivLoaderRegistryProvider.
SpatialViewer External Deck Layer Support packages/vis/src/SpatialCanvas/SpatialViewer.tsx	Extends SpatialViewerProps with optional deckProps: Partial<DeckGLProps> and forwards it to both Viv-based and fallback rendering paths. Fallback path composes provided layers with Viv-normalized layers from deckProps?.layers, spreads deckProps into DeckGL props, and allows override of controller/style while preserving defaults.
SpatialCanvas Renderer Hook Integration packages/vis/src/SpatialCanvas/index.tsx	Refactors SpatialCanvas to use useSpatialCanvasRenderer as primary source of layer data, tooltip/bounds helpers, and rendering state. Removes old useLayerData/getAvailableElements wiring and inline view-framing effects. Simplifies selectedLayerWorldBounds from memoized block to inline IIFE. Re-exports SpatialCanvasViewer and renderer utilities.
Public API Exports packages/vis/src/SpatialCanvas/index.tsx, packages/vis/src/index.ts	Expands exports to include SpatialCanvasViewer, useSpatialCanvasRenderer, layer composition utilities (composeSpatialDeckLayers, shouldAutoFitSpatialView, shouldRenderInternalTooltip), and types (SpatialCanvasViewerProps, SpatialCanvasViewerRenderTooltip).
Unit Tests & Export Validation packages/vis/tests/index.spec.tsx, packages/vis/tests/spatialCanvasViewer.spec.ts	Adds export assertions for SpatialCanvasViewer and utilities. New spec file verifies composeSpatialDeckLayers layer order, shouldAutoFitSpatialView framing conditions, and shouldRenderInternalTooltip eligibility logic.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• Taylor-CCB-Group/SpatialData.js#30: This PR directly implements the controlled SpatialCanvasViewer "bridge path" and deck.gl layer composition described in the MDV roadmap update.
• Taylor-CCB-Group/SpatialData.js#20: Both PRs implement view-state auto-fitting around the concept of fitting the camera when viewState is unset; this PR adds the autoFit/shouldAutoFitSpatialView plumbing in SpatialCanvasViewer.
• Taylor-CCB-Group/SpatialData.js#18: Both PRs modify the SpatialCanvas rendering pipeline and SpatialViewer.tsx layer composition alongside Viv; this PR adds deckProps support and a bridge viewer that reuses the Viv/deck stack.

Poem

🐰 A canvas now stands, both headless and free,
Composed layers stack up from SpatialData trees,
MDV controls the state like a puppeteer's hand,
While deck.gl and viv work in harmony grand—
Bridge paths unite them, a bridge to the promised land! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: introducing a headless SpatialCanvasViewer component with design notes for future iterations.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/progress-mdv-integration

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

packages/vis/tests/index.spec.tsx (1)

30-31: ⚡ Quick win

Cover all new runtime exports in the barrel export test.

Please also assert shouldRenderInternalTooltip and useSpatialCanvasRenderer here so root API regressions are caught in one place.

Suggested test additions

   expect(VisExports.composeSpatialDeckLayers).toBeDefined();
   expect(VisExports.shouldAutoFitSpatialView).toBeDefined();
+  expect(VisExports.shouldRenderInternalTooltip).toBeDefined();
+  expect(VisExports.useSpatialCanvasRenderer).toBeDefined();

As per coding guidelines, "Prefer types that match runtime behavior ... at API boundaries."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/vis/tests/index.spec.tsx` around lines 30 - 31, Add runtime
assertions for the two missing exports in the barrel export test by adding
expectations that shouldRenderInternalTooltip and useSpatialCanvasRenderer are
defined (similar to the existing
expect(VisExports.composeSpatialDeckLayers).toBeDefined() and
expect(VisExports.shouldAutoFitSpatialView).toBeDefined()). Locate the test in
the same spec where VisExports is used and add
expect(VisExports.shouldRenderInternalTooltip).toBeDefined() and
expect(VisExports.useSpatialCanvasRenderer).toBeDefined() so runtime API
regressions are caught.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/docs/vis/mdv-release-checklist.mdx`:
- Line 140: The two MDV docs are inconsistent about Viv PR `#924` (one says
"merged" and mentions deck `9.2.9`, the integration roadmap still lists it as
open); update the wording so both pages match — either mark PR `#924` as merged on
the integration roadmap or revert the release-checklist wording to "open" or use
a date-scoped phrase like "as of <date>, PR `#924` is merged" — ensure the same
phrasing appears for Viv PR `#924` and deck `9.2.9` across the release-checklist
and integration roadmap documents to eliminate ambiguity.

---

Nitpick comments:
In `@packages/vis/tests/index.spec.tsx`:
- Around line 30-31: Add runtime assertions for the two missing exports in the
barrel export test by adding expectations that shouldRenderInternalTooltip and
useSpatialCanvasRenderer are defined (similar to the existing
expect(VisExports.composeSpatialDeckLayers).toBeDefined() and
expect(VisExports.shouldAutoFitSpatialView).toBeDefined()). Locate the test in
the same spec where VisExports is used and add
expect(VisExports.shouldRenderInternalTooltip).toBeDefined() and
expect(VisExports.useSpatialCanvasRenderer).toBeDefined() so runtime API
regressions are caught.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0c42ba39-a112-4175-9e73-dd632e3ad00f

📥 Commits

Reviewing files that changed from the base of the PR and between d2da16e and 2dc6ec6.

📒 Files selected for processing (8)

• docs/docs/vis/mdv-integration.mdx
• docs/docs/vis/mdv-release-checklist.mdx
• packages/vis/src/SpatialCanvas/SpatialCanvasViewer.tsx
• packages/vis/src/SpatialCanvas/SpatialViewer.tsx
• packages/vis/src/SpatialCanvas/index.tsx
• packages/vis/src/index.ts
• packages/vis/tests/index.spec.tsx
• packages/vis/tests/spatialCanvasViewer.spec.ts