feat(core): js-parity global-state expression support by NEKOYASAN · Pull Request #4516 · maplibre/maplibre-native

NEKOYASAN · 2026-08-24T08:40:16Z

resolve #3302

Summary

add the global-state expression and the root state property, with the runtime API style::Style::setGlobalStateProperty / getGlobalState
track the state keys referenced by each expression so a change only re-evaluates and relayouts the layers and sources referencing a changed key (parity with gl-js getGlobalStateRefs)
align failed zoom-only property expression evaluation with GL JS: evaluation failures now use the property's style-spec default instead of value-initializing its type. This applies to all zoom-only expressions, not only global-state expressions
reject global-state updates until the style JSON has loaded, matching GL JS, and expose style::Style::isLoaded so platform bindings can distinguish this point from full resource loading
and platform apis

Verification

cmake --build build-macos-metal --target mbgl-test-runner and the style/expression suites, including the new GlobalStateExpression.*, Style.GlobalState*, Style.Visibility*, and Layer.SymbolLayerOverrides tests
Android: :MapLibreAndroid:testOpenglDebugUnitTest plus instrumentation tests on an emulator (RuntimeStyleTests, MapSnapshotterTest), arm64 native build
iOS: bazel test //platform/ios/test:ios_test --//:renderer=metal (MLNStyleTests, MLNExpressionTests)
Node: built the addon locally and ran the tape tests (test/js/global_state.test.js, map.test.js)

Note

The code in this PR was written with the help of Claude (Fable 5), under my instruction and review.

louwers

Looked through it, looks quite good!

Let's port the render tests from MapLiibre GL JS. https://github.com/maplibre/maplibre-gl-js/tree/main/test/integration/render/tests/global-state

NEKOYASAN · 2026-08-25T00:12:28Z

@louwers thank you!
I ported the rendering test from GL JS!
I also fixed an issue with how unspecified (default) values were being handled.

github-actions · 2026-08-25T00:42:22Z

Bloaty Results 🐋

Compared to main

    FILE SIZE        VM SIZE    
 --------------  -------------- 
  +1.6% +2.83Mi  +1.9%  +676Ki    TOTAL

Full report: https://maplibre-native.s3.eu-central-1.amazonaws.com/bloaty-results/pr-4516-compared-to-main.txt

Compared to d387090 (legacy)

    FILE SIZE        VM SIZE    
 --------------  -------------- 
   +58% +67.1Mi  +487% +29.1Mi    TOTAL

Full report: https://maplibre-native.s3.eu-central-1.amazonaws.com/bloaty-results/pr-4516-compared-to-legacy.txt

github-actions · 2026-08-25T00:44:07Z

Benchmark Results ⚡

Benchmark                                                          Time             CPU      Time Old      Time New       CPU Old       CPU New
-----------------------------------------------------------------------------------------------------------------------------------------------
OVERALL_GEOMEAN                                                 +0.0025         +0.0027             0             0             0             0

Full report: https://maplibre-native.s3.eu-central-1.amazonaws.com/benchmark-results/pr-4516-compared-to-main.txt

github-actions · 2026-08-25T00:46:06Z

Bloaty Results (iOS) 🐋

Compared to main

    FILE SIZE        VM SIZE    
 --------------  -------------- 
  +0.6% +99.0Ki  +0.6% +96.0Ki    TOTAL

Full report: https://maplibre-native.s3.eu-central-1.amazonaws.com/bloaty-results-ios/pr-4516-compared-to-main.txt

louwers · 2026-08-25T08:23:48Z

Nice!

NEKOYASAN · 2026-08-25T11:11:44Z

It looks like CI was failing because I had copied v8.json directly from @maplibre/maplibre-gl-style-spec. I’ve now made a few Native-specific adjustments to it.
I’m not entirely sure this is the ideal approach, but I found several other PRs that handled similar style-spec synchronization issues this way, so I followed that precedent for now.

NEKOYASAN · 2026-08-27T00:17:24Z

I'm truly sorry that this turned into such a huge PR...

Based on the comments below, I have added tests and confirmed that everything is working as expected.
maplibre/maplibre-style-spec#886 (comment)

johncarmack1984

Saw Bart asking for reviews on this in the newsletter thread, thought I'd pitch in.

Read the core and platform halves against GL JS's implementation (style.ts, the spec's global_state.ts and visibility.ts). The semantics line up as far as I can trace. Null when unset, defaults from state, null resets to the default, re-evaluation scoped to the keys that changed. Filters in the query paths, format overrides and the color ramps too.

For anyone looking at the two red checks: those are the Android render-test legs from a workflow_run on main at be3f03b, which failed once and passed on the rerun. Every run on this PR's own head (fc32f1f) is green.

Looked into @HarelM's note about porting the rest of the GL JS global-state tests: 59 of the 69 are in here. The other 10 are sky, projection, and the two *-layer-opacity properties, none of which exist in native yet. Should stubs or // TODO comments go in to keep parity, or something else?

Implements the maplibre-gl-js global-state feature (maplibre#3302)

implementation

global state

MapSnapshotter

for more information, see https://pre-commit.ci

2.

This reverts commit 04556ef.

some properties

NEKOYASAN · 2026-09-07T03:42:13Z

@johncarmack1984 Thank you for your review!

For anyone looking at the two red checks: those are the Android render-test legs from a workflow_run on main at be3f03b, which failed once and passed on the rerun. Every run on this PR's own head (fc32f1f) is green.

I rebased upstream/main, and all 50 checks passed.

The other 10 are sky, projection, and the two *-layer-opacity properties, none of which exist in native yet. Should stubs or // TODO comments go in to keep parity, or something else?

I think it is fine to exclude these for now. I could not find any precedents in the Native codebase where stubs or TODO comments were added for Mapbox GL JS rendering test features that are not yet supported on the Native side. so I believe it would be better to port them together when implementing those features themselves.

johncarmack1984

Read the four new commits against the threads. Submodule is back on main's commit. Tile::setLayers carries the state now, and setGlobalState went with it. The query paths hand the state over next to the options instead of on the public structs. The pre-load call throws before the style is marked mutated, and isLoaded() is in the changelog. Range-diff of the rebased series against what I read last week is all =, so nothing else moved. All 49 checks green on the head. Good from me (with the caveat that I am just a citizen-contributor, not a maintainer!). Hope this was helpful! :)

johncarmack1984 · 2026-09-07T15:38:12Z

+- (void)setGlobalStateValue:(id)value forProperty:(NSString *)propertyName {
+  MLNLogDebug(@"Setting global state property: %@", propertyName);
+  self.rawStyle->setGlobalStateProperty(propertyName.UTF8String, MLNValueFromJSONObject(value));
+}


One iOS side effect of the new throw: MLNMapSnapshotter.style hands out an MLNStyle before the style has loaded, and this call goes straight into core. A pre-load call used to drop the value; now it terminates the process, since nothing on the ObjC side catches it. The sibling methods in this file wrap the core call in try/catch and raise an NSException. Same wrapper here would match the Kotlin IllegalStateException. Not blocking.

Thank you for your review! your review is very helpful to me!

I was satisfied after fixing the Android side... I have now also fixed the iOS side to throw an NSInternalInconsistencyException.

I also wanted to review the globe view PR in appreciation of your review, but it turned out to be quite difficult... ;_;

haha yeah that one is HUGE, but thanks for taking a crack at it :)

github-actions Bot added build Related to build, configuration or CI/CD android iOS core Changes that affect the C++ core of MapLibre Native node labels Aug 24, 2026

NEKOYASAN changed the title ~~feat: js-parity global-state expression support~~ feat(core): js-parity global-state expression support Aug 24, 2026

NEKOYASAN marked this pull request as ready for review August 24, 2026 15:01

louwers added the js-parity label Aug 24, 2026

louwers reviewed Aug 24, 2026

View reviewed changes

NEKOYASAN requested a review from louwers August 25, 2026 07:45

louwers mentioned this pull request Aug 25, 2026

Design Proposal: Global map state maplibre/maplibre-style-spec#886

Closed

NEKOYASAN force-pushed the feat/js-compat-global-state branch from 9c81af9 to fc32f1f Compare August 30, 2026 07:08

github-actions Bot added the WebGPU label Aug 30, 2026

louwers mentioned this pull request Sep 1, 2026

[Newsletter]: Call for Submissions - August Newsletter maplibre/maplibre.github.io#815

Closed

johncarmack1984 reviewed Sep 1, 2026

View reviewed changes

Comment thread vendor/expected-lite

Comment thread src/mln/tile/tile.hpp Outdated

Comment thread include/mln/renderer/query.hpp Outdated

Comment thread src/mln/renderer/data_driven_property_evaluator.hpp

Comment thread src/mln/style/style_impl.cpp

NEKOYASAN added 8 commits September 7, 2026 00:50

Add support for the global-state expression and state style property

b7d07e6

Implements the maplibre-gl-js global-state feature (maplibre#3302)

perf(core): track global-state refs per key to limit re-evaluation

738b3b7

refactor(core): remove redundant comments from global-state

a1d9a17

implementation

feat(android): add global-state runtime API and expression builder

0d1c9cc

feat(ios): add global-state runtime API and NSExpression support

2a3353a

docs: remake changelog texts and document mgl_globalState

89e3090

feat(android): add global-state API to MapSnapshotter

fa43402

feat(node): add global-state runtime API

e0c2812

NEKOYASAN and others added 23 commits September 7, 2026 00:50

fix(core): evaluate runtime-set visibility expressions against current

d818194

global state

fix(core): keep global-state dependency through format section overrides

8b4fb76

fix(android): query the style's load state instead of tracking it in

9283658

MapSnapshotter

feat(android): allow setting layer visibility as an expression

a7a0546

feat(ios): allow setting layer visibility as an expression

da94ac5

[pre-commit.ci] auto fixes from pre-commit.com hooks

5999786

for more information, see https://pre-commit.ci

feat(android): add Layer#getVisibilityExpression

e42efbe

fix(core): address global-state CI build failures

cb3351e

update: v8.json from @maplibre/maplibre-gl-style-spec

b388d5d

chore: port integration test from gl-js

56fe296

fix(core): use property defaults when expression evaluation fails

0bfffc5

2.

Revert "update: v8.json from @maplibre/maplibre-gl-style-spec"

45aedbe

This reverts commit 04556ef.

Reapply update v8.json from @maplibre/maplibre-gl-style-spec without

72433f6

some properties

test: port global-state render tests from gl-js

ee02997

fix(core): defer visibility evaluation until global state is available

5b07b3b

fix(core): align global-state null semantics with gl-js

89dcf1e

fix(android): allow snapshotter style access after style load

a52a206

test(core): add global-state update regression coverage

a75c0e9

test(darwin): ignore fill-extrusion-pattern/global-state test

9441917

refactor(core): pass global state through Tile::setLayers

86ab6e6

refactor(core): pass global state separately in query paths

9cedafc

fix(core): reject global-state updates before style load

b300d1c

chore: restore expected-lite submodule revision

b8969dd

NEKOYASAN force-pushed the feat/js-compat-global-state branch from fc32f1f to b8969dd Compare September 6, 2026 15:50

NEKOYASAN requested a review from johncarmack1984 September 7, 2026 03:42

johncarmack1984 reviewed Sep 7, 2026

View reviewed changes

NEKOYASAN added 2 commits September 8, 2026 01:21

fix(darwin): convert global-state errors to NSException

8905d43

Merge branch 'main' into feat/js-compat-global-state

dc75a57

Uh oh!

Uh oh!

Conversation

NEKOYASAN commented Aug 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Verification

Note

Uh oh!

louwers left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

NEKOYASAN commented Aug 25, 2026

Uh oh!

github-actions Bot commented Aug 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bloaty Results 🐋

Full report: https://maplibre-native.s3.eu-central-1.amazonaws.com/bloaty-results/pr-4516-compared-to-main.txt

Uh oh!

github-actions Bot commented Aug 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Aug 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bloaty Results (iOS) 🐋

Full report: https://maplibre-native.s3.eu-central-1.amazonaws.com/bloaty-results-ios/pr-4516-compared-to-main.txt

Uh oh!

louwers commented Aug 25, 2026

Uh oh!

NEKOYASAN commented Aug 25, 2026

Uh oh!

NEKOYASAN commented Aug 27, 2026

Uh oh!

johncarmack1984 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

NEKOYASAN commented Sep 7, 2026

Uh oh!

johncarmack1984 left a comment

Choose a reason for hiding this comment

Uh oh!

johncarmack1984 Sep 7, 2026

Choose a reason for hiding this comment

Uh oh!

NEKOYASAN Sep 7, 2026

Choose a reason for hiding this comment

Uh oh!

johncarmack1984 Sep 7, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

NEKOYASAN commented Aug 24, 2026 •

edited

Loading

louwers left a comment •

edited

Loading

github-actions Bot commented Aug 25, 2026 •

edited

Loading

github-actions Bot commented Aug 25, 2026 •

edited

Loading

github-actions Bot commented Aug 25, 2026 •

edited

Loading