RFC/POC: Extend View system to support multi-canvas rendering

[ibgreen]

Goal

Add opt-in multi-canvas presentation while preserving the existing single-canvas Deck API and behavior.

Compatibility and API

• DeckProps.canvas retains its existing scalar type, automatic canvas creation, event-manager lifecycle, and integration behavior.
• Experimental DeckProps._canvases is intentionally a separate opt-in, as agreed during review follow-up, so existing React, Mapbox, and other single-canvas integrations cannot accidentally change behavior.
• View.canvasId assigns a view to one presentation canvas; omitted ids select the first configured canvas.
• Deck.getEventManager() already exists on master; this PR preserves the existing API and resolves the manager for the requested view.
• No React implementation or React documentation changes are included.

Changes

• Present one shared layer stack into independently sized HTML canvases using luma.gl presentation contexts.
• Preserve custom .deck-events-root handling and route controllers, DOM events, and picking to their source canvas.
• Position view-scoped widgets relative to their presentation canvas while keeping widget DOM under the existing shared root.
• Clear and present canvases when their views move or are removed.
• Document the experimental API, compatibility boundary, view assignment, picking, and widget behavior.
• Add TSDoc for canvas targets, manager helpers, picking options, and view routing.
• Cover multi-canvas presentation, custom event roots, canvas-aware picking, orphaned canvas clearing, and preservation/finalization of the existing single-canvas event manager.
• Preserve strict Mapbox filtering assertions while waiting deterministically for the first redraw.

Review stack

1. refactor(core): honor canvas contexts throughout render passes #10474, refactor(core): size and filter viewports by canvas #10475, and fix(core): position widgets relative to their canvas #10491 — merged rendering/picking, viewport-layout, and widget-positioning preparation.
2. This PR — core multi-canvas presentation and documentation, rebased onto current master.
3. docs(core): add standalone multi-canvas cities example #10492 — the standalone four-city example, stacked on this PR.

Validation

• yarn — workspace dependencies updated to match current master.
• yarn lint — passes; existing repository-wide lint warnings remain unchanged.
• ./node_modules/.bin/tsc -p modules/core/tsconfig.json --noEmit --pretty false — passes.
• ./node_modules/.bin/vitest run --project node --silent — 22 tests passed.
• Normal repository pre-commit checks — lint and all 22 Node tests passed.
• Stacked example bundles successfully with esbuild and remains limited to its four example/documentation files.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 72fa41c755

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[coveralls]

coverage: 83.158% (+0.03%) from 83.127% — ib/multi-canvas-rfc into master

[Pessimistress]

• Did you test widgets at all? I did not see any changes to the widget manager on placement handling w/ multiple canvases.

• I strongly recommend that you exclude react from the initial PR. The implementation looks very hacky and not conforming to reactive patterns. And this is adding on top of existing complex React flow with known bugs.

[ibgreen-openai]

@Pessimistress Addressed the requested review changes and rebased the feature on the now-merged preparation work:

• Widgets: the actual multi-canvas Deck integration test now mounts one FullscreenWidget per view, verifies both remain beneath the shared widget root, and checks their independent canvas-relative offsets and dimensions. The four-canvas cities example also mounts a view-scoped ZoomWidget on every canvas.
• React: no modules/react or React-test files are included in this PR. The developer guide now shows the plain JavaScript Deck API and the actual HTML canvas IDs; React integration is intentionally deferred.
• Custom event roots: each presentation canvas retains its own .deck-events-root resolution and dedicated event manager, with integration coverage.
• Removed views: unused canvases are explicitly cleared and presented; regression coverage now verifies the exact framebuffer, transparent clear color, depth clear, and presentation.

Validation: core TypeScript checking, repository lint/pre-commit smoke tests, and all 90 focused browser tests pass.

[ibgreen-openai]

@Pessimistress I re-audited every review comment and updated the rebased stack:

• Backward compatibility: as agreed in the follow-up Slack conversation, experimental _canvases remains separate from the existing scalar canvas prop. The API documentation and TSDoc now explicitly explain that this protects current single-canvas, React, and overlay integrations.
• Single-canvas lifecycle: the new regression verifies ordinary setProps() preserves the existing event manager, never destroys its listeners prematurely, and finalization destroys it exactly once.
• Review scope: no React implementation/docs changes, no widget-specific logic in the widget manager, and no newly exposed event-manager API; getEventManager() already exists on master.
• Existing requests: custom .deck-events-root handling, per-view widget positioning, canvas-aware picking, and explicit clearing/presentation of orphaned canvases remain covered.
• Stack: refactor(core): honor canvas contexts throughout render passes #10474, refactor(core): size and filter viewports by canvas #10475, and fix(core): position widgets relative to their canvas #10491 are merged; this PR is rebased onto current master; docs(core): add standalone multi-canvas cities example #10492 is restacked and remains a four-file standalone example.

Validation: yarn lint, core TypeScript checking, the complete 22-test Node suite, the normal pre-commit checks, and the example bundle all pass. I also replied directly to every previously unanswered or potentially misleading review thread.