feat(core): track controlled props to give widgets signal on user intent

[chrisgervang]

Summary

This PR introduces a controlled-props tracking mechanism so that widgets can safely manage props the application has left unset, without stomping on props the user has explicitly declared.

Problem

The React wrapper called deck.setProps(forwardProps) on every render, passing a fully merged snapshot that included framework defaults and wrapper-owned overrides (e.g. views: null, layers: []). This meant any prop a widget wrote would be overwritten on the next re-render — even if the user never declared that prop in JSX.

Separately, there was no way for a widget to know whether a given prop was user-controlled or available for the widget to own.

Solution

Deck._controlledProps: Set<string>
Tracks which props were explicitly declared by the user.

Deck.setProps (patch — unchanged contract)
Accumulates into _controlledProps. Once a prop is declared imperatively, it stays controlled.

Deck._setPropsSnapshot(userProps, allProps?) (framework wrappers)

Replaces _controlledProps on every call so it always reflects the current declaration. Props the user never declared are left untouched, allowing widgets to manage them. Props that were declared last render but are absent this render are reset to their defaultProps value - so removing a prop from JSX behaves identically to before.

• userProps is what drives _controlledProps
• allProps (defaults to userProps) is what gets passed to _applyProps

Deck.isControlled(key)
Public query for widgets. Returns true only for props the user declared.

Deck._setWidgetProps(props)
Applies a prop patch without touching _controlledProps. Widgets must use this (via Widget.updateDeckProps) instead of deck.setProps to avoid incorrectly marking props as user-controlled.

Widget.updateDeckProps(props)
Protected helper on the Widget base class. The correct way for any widget to write deck props.

React wrapper (deckgl.ts)

Now calls deck._setPropsSnapshot(userProps, explicitProps) instead of deck.setProps(forwardProps).

explicitProps contains wrapper-owned props (always applied) plus only what the user actually wrote in JSX; userProps is explicitProps minus WRAPPER_OWNED_KEYS (style, width, height, parent, canvas, onViewStateChange, onInteractionStateChange), so _controlledProps reflects only what the user declared.

layers and views are included in both only when the user declared them or JSX children contributed them — extractJSXLayers gains hasJSXLayers/hasJSXViews for this. The reset-on-drop logic in _setPropsSnapshot ensures that if the user stops declaring one of these, it is still reset to its default.

Widget usage pattern (e.g. SplitterWidget)

onAdd({deck}) {
  if (deck.isControlled('views')) {
    // User is driving views — back off
    return;
  }
  this.updateDeckProps({views: this._buildViews()});
}

On re-render, if the user never wrote views in JSX, _setPropsSnapshot leaves this.props.views untouched. The widget’s views survive.

Caller	Entry point	_controlledProps effect
User (patch)	setProps	accumulates
React / framework wrapper	_setPropsSnapshot	replaces
Widget	updateDeckProps → _setWidgetProps	untouched

---

Note

Medium Risk
Changes Deck/DeckGL prop-application semantics and introduces new internal update paths; regressions could surface in React wrappers or widget-driven props if controlled/uncontrolled detection is wrong. Scope is moderate and covered by new unit tests, with minimal security impact.

Overview
Adds controlled-props tracking to Deck so widgets can detect whether a prop was explicitly set by the app via new deck.isControlled(key).

Updates prop application to distinguish user patch updates (setProps accumulates controlled keys) vs framework snapshot updates (_setPropsSnapshot replaces the controlled set and resets dropped keys to defaultProps), plus a widget-safe path (_setWidgetProps, exposed as Widget.updateDeckProps) that won’t mark props as user-controlled.

Adjusts the React DeckGL wrapper to snapshot only user-declared keys (excluding wrapper-owned overrides and omitting layers/views unless explicitly provided/derived from JSX), and adds guards in Mapbox interleaved rendering to skip a render cycle when viewport dimensions are 0. Adds tests covering controlled-props behavior and widget-managed props surviving React re-renders.

^{Written by Cursor Bugbot for commit f7f93bd. This will update automatically on new commits. Configure here.}

[coveralls]

coverage: 91.015% (+0.004%) from 91.011%
when pulling 63c115e on claude/analyze-breaking-change-react-XAfVA
into 3c69e49 on master.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}