Nov 2024 design discussion: composable style management

[sargunv]

In November 2024, there was a Slack discussion here about a Composable API for a the map style, which resulted in us moving away from internally managed source/layer IDs to explicitly user-provided ones.

It's probably important context to preserve, especially in light of issues like #236 that might have us re-evaluate whether that pattern for managing IDs is actually what we should stick with or not.

Saving it here to preserve.

---

sargunv
Nov 11th, 2024 at 12:31 AM
Over the last couple days I’ve been thinking about the Composable API for managing map styles, and here’s my thoughts on the pitfalls involved and their solutions. Going to update my library with the changes described here: https://osmus.slack.com/docs/T029HV94T/F0809L1C7EX (edited)

(see: Canvas)

:star-struck:
3

39 replies

Patrick Wolowicz
Nov 11th, 2024 at 12:53 AM
Interesting - good read, thanks. One thing to consider (which I think would be possible via your proposal, but is missing in the ones that are trying to hide source and layer ids from users): remember that not all source ids and layer ids are generated on the client. Many arrive via the style.json file, and developers may want to manipulate these too: a developer may want to make a layer tappable for example, or change some styling parameters. As these source ids and layer ids are not available at compile time, any API needs to have a way of accessing and manipulating source ids and layer ids that were added at run time.
☝️
1

sargunv
Nov 11th, 2024 at 1:04 AM
For using base map sources in Compose layers, it should be easy to create a Composable that allows the user to retrieve a source handle by id, and pass that handle to Layer composables.

Modifying base map layers is an interesting case; I'll have to think more about how and whether to handle that. Do you have example use cases you can share? My gut says this should happen via some mutable state connected to the map composable, rather than in the style composition, but am unsure.

For both sources and layers, we'd probably want to ensure this API for overriding / editing base map sources and layers can't (easily) do the same to those already defined in Compose, as some assumptions might break if the same layer is defined in two different places in the API 😅 This part is easily solved by continuing to hide the true IDs of Composable sources/layers from the user (edited)

Patrick Wolowicz
Nov 11th, 2024 at 2:17 AM
Sure. Typical features that clients ask for - they provide a source (e.g. “data”) and layer (e.g. “poi”) and would like:

• any feature of the “poi” layer to be tappable. When tapped, the feature ID is used for an http query to fetch data and show a sheet of info
• adding a button to the UI, where when tapped, the look of all “poi” in the map gets manipulated, for example making them all 20% larger for emphasis, or hiding them completely.

westnordost
Nov 11th, 2024 at 5:34 AM
I agree on that the latter mock-up looks much better than the former mock-up.

To me, a few things look a little weird/unexpected:

• that the LineLayer ("amtrakRoutes-outline") is just bare in that block. But, I don't know whether this layer would end up at the top, or the bottom, or just at the top of the loaded style, or where, as it is not written anywhere explicitly. I guess order matters, so anything written further down is rendered more at the top. But it seems, anchorLayers can be anywhere in the block, because it kind of overrides the normal order. This seems a bit weird/inconsistent to me. If all layers must be anchored somewhere, it would be explicit where the layers go.
• Smurf naming for line style properties: if LinePaint describes the style for LineLayers, then the line-part of lineWidth, lineColor, etc. seem to be superfluous.
• if Anchor is the only parameter to anchorLayers , the API could also be like Anchor.below("labels"), Anchor.Top, Anchor.above("labels") etc. This would be quite similar to e.g. the API for horizontalArrangement in Compose Row s. There, we have e.g. Arrangement.spacedBy(8.dp) , Arrangement.Start , etc. - Although, perhaps not that comparable, because the latter are properties of a composable, the Anchor stuff are composables themselves. The naming convention, by the way, for composables that do not return a value is UpperCase. If you keep it the way it is, I would propose "AnchoredLayers", cause "anchorLayers" sounds like an instruction (-> imperative programming)
  (edited)

sargunv
Nov 11th, 2024 at 10:04 AM

That the LineLayer is just bare in that block

I think most users will be content with placing their compose layers on top of the base map style, so it feels intuitive to me to have the default be Anchor.Top. Anchors are more for advanced users wishing to place compose layers between base map layers. These users can explicitly declare Anchor.Top if they feel it makes their code clearer.
Maybe the styleUrl param should be baseStyleUrl to make it more clear it's the "base" (and therefore below, by default) the user's layers?

Smurf naming

Yup agreed, I let Copilot generate these based on the names in the style.json docs but can rename them to be less smurfy
😱
1

sargunv
Nov 11th, 2024 at 10:29 AM

Naming convention for composables that do not return a value

Oops yeah. I've fixed the mock up.

The API could also be like

I see, so Anchor.Bottom would be a Composable providing the anchor, instead of a parameter to LayeredAnchors providing the anchor? Reasonable I think, though it means it's both a data class and a composable function. The data class could be internal though, so for the user it's just a function. Will need to see how the overload pans out (or just rename the now-internal data class to free up that name for the API)

10:31

New mock up:

MaplibreMap(styleUrl = style) {
  val amtrakRoutes = rememberGeoJsonUrlSource(key = "amtrakRoutes", dataUrl = Res.getUri(...))
  
  LineLayer(
    key = "amtrakRoutes-outline",
    source = amtrakRoutes,
    paint = LinePaint(
      lineWidth = interpolate(exponential(const(2)), zoom(), 0 to const(2), 10 to const(4)),
    ),
  )

  Anchor.Below("labels") {
    LineLayer( ... )
  }
}

sargunv
Nov 11th, 2024 at 10:43 AM

any feature of the “poi” layer to be tappable. When tapped, the feature ID is used for an http query to fetch data and show a sheet of info

I haven't worked on callbacks yet, but if this is a callback on the map component, this would work the same for base layers and compose layers. If it's a callback on the compose layer, we'd need some alternative for base layers.

adding a button to the UI, where when tapped, the look of all “poi” in the map gets manipulated, for example making them all 20% larger for emphasis, or hiding them completely.

Is there any reason for the user to provide this layer as part of the base style.json rather than as a compose layer? (which could then react to changes in state, like from button presses)

Something on my backlog to investigate in the future is an approach that decouples the Composable style management from the map itself. Consider a model where the map exposes a mutable State based API for managing a style, and the Composable style management manipulates that State. Ultra advanced users who want to mutate the base map layers can work with that State directly, while everyone else just ties it to a style composition and works in the composition for dynamic layer styling like the current model (edited)

Ian Wagner
Nov 11th, 2024 at 4:59 PM
One more point on the IDs vs references question (which we addressed in a similar manner for the SwiftUI DSL) is that it’s not just about modifying basemap layers but about referencing sources by ID which are already in the style and for which you want to add a new layer.

There are plenty of reasons you’d want to modify basemap layers though too. Localization, for example, is not addressed by the MapLibre style spec (this is hard to generalize). App code could invoke an API to get the current locale, and then construct an expression based on properties of the source which the developer knows. This could even be a complex expression like “German if it’s available; otherwise English; otherwise some romanization; finally the local name.”

sargunv
Nov 12th, 2024 at 12:02 AM
Thanks for the added color there! Will have to check out how the SwiftUI DSL tackles this.

Localization is an interesting use case. Thinking through some potential approaches:

• Composable, write-only properties: provide a way for a Layer defined in the Composition to fully replace a layer in the basemap (rather than just insert above/below/etc). The overriding layer uses the original layer’s properties as defaults (instead of the MapLibre defaults). If the overriding layer is removed from the composition, the original layer is restored.
  • this could actually be two features that combine to provide this functionality: one is an Anchor.Replace(layerId) anchor, and the other is some defaultPropertiesFrom = layerId property on layer composables
• Mutable state, write-only properties: expose a mutable state control surface to the map composable. Include methods to get a layer, and then the user can call setters on these layers (in a SideEffect or whatever).
• Mutable state, read-write properties: same as above, except include property getters. Requires writing methods to convert native sdk’s expression objects back to Multiplatform expression objects.

I think the solution should be the first or the third (or both)? The first keeps everything as declarative as possible, while the third allows for the layer overriding logic to use the existing property values. The backwards conversion might be prohibitive though, especially for the iOS NSExpression stuff (or at least, I have no idea how to traverse NSExpressions) (edited)

westnordost
Nov 12th, 2024 at 3:22 PM

Hmm, before going down that hole maybe it would be worth it to review what are the advantages of not using (string) Ids for sources but pass by reference - I mean, the advantage of using string Ids for sources seems to be that it is easier (for the library author) while maintaining full flexibility. The downside is that the user can add typos when referring to the same source multiple times (but, well, he could just use a constant).

On the mentioned approaches: I would expect that if I re-define a layer that already exists in the base style, that all properties are overwritten, i.e. the layer is replaced. I would find it unintuitive if there was even an option to somehow inherit from the style in the base style. (edited)

sargunv
Nov 12th, 2024 at 6:03 PM

review what are the advantages of not using (string) Ids for sources but pass by reference

The reasoning is if the user has full control over the ID, they can do things with conditional logic in the composition that result in layer nodes being inserted with duplicate IDs. Even if the user didn't actually create two layers with the same ID, there could be some conditional logic in the composable that results in a layer node being removed in one place and added in another place with the same id, but applier execution might result in the addition happening before the removal. By managing IDs internally, we sidestep that issue by ensuring IDs are all unique.

There are alternative solutions though; consider Compose UI has multiple phases. First the UI tree is composed in its entirety, then layout calculations are done for the whole tree, and then drawing is done with the whole tree (skipping things that didn't recompose ofc). If we want the user to directly control IDs, we can do something similar; do layer insertion/removal on the Style as a separate phase that happens after composition. Not 100% sure how that's implemented but could probably figure it out. This would simplify layer touch callbacks if we do them at the Map level (since we don't have to map the generated ID back to the user-provider key).

6:07

On the mentioned approaches: I would expect that if I re-define a layer that already exists in the base style, that all properties are overwritten, i.e. the layer is replaced.

Slight disagree, in that I'd expect it to throw an exception for duplicate IDs.

If there's an purposeful API to replace a Layer, then yes I'd expect the entire layer to be overwritten (this could be a new Anchor type, with some extra logic to remember the overwritten layer in case the override is removed from the composition)

I would find it unintuitive if there was even an option to somehow inherit from the style in the base style.

The option feels a bit weird to me too. It's a possibility for handling the "change one property of a base layer" use case declaratively but if it's too weird we can limit those kinds of use cases to an imperative, mutable control surface? (edited)
✅
1

Ian Wagner
Nov 12th, 2024 at 6:10 PM

review what are the advantages of not using (string) Ids for sources but pass by reference

At the risk of stating the obvious, the advantage is that you don’t have to use stringly typed IDs 😉 String IDs open up all sorts of errors which are frustrating, always result in hard app crashes, and cannot possibly be checked until runtime. Not using IDs at all is a very strong feature.

Yes, sometimes you do really need to be able to reference a layer by ID, so in the SwiftUI DSL we do have ways of doing this, but the preferred way IMO should be reference-based. IDs are just an implementation detail unless you’re making changes to an existing style that wasn’t built using a composable approach (ex: extending a JSON basemap style).

6:14

One interesting thing this discussion highlights is that there is a lot more overlap than might be initially apparent between style manipulation (even creation?) and composable UI 😉 I’m glad this is starting to come up. I’ve had some ideas brewing about this for a while. While the result is probably split into different modules/projects, I really do think it’d be valuable to the MapLibre community to have really high-level style manipulation libraries.

I’m thinking of things like being able to recompose your style so that labels are a function of your current locale. Or “add this layer under all labels.” There’s a lot that would be much easier with high-level interfaces like a Kotlin DSL.

sargunv
Nov 12th, 2024 at 6:16 PM

Yes, sometimes you do really need to be able to reference a layer by ID

I understand there's cases where referencing base style layers by ID is necessary. Are there cases where referencing Compose / SwiftUI layers by ID is necessary?

One that comes to mind is in callbacks, where the map says "user tapped feature 0 in layer 123456" and since id 123456 was generated by the library, the user can't condition on it. A couple solutions come to mind:

• Since I already require the user to pass a key (to prevent unnecessary recompositions) I can map the ID back to the user-provided key in the callback
• The callback can be tied to the layer composable instead of the map composable, so the user doesn't need to condition on id at all (and never sees it)
• The above alternative where IDs are user-provided and style updation is a separate phase

6:19

One interesting thing this discussion highlights is that there is a lot more overlap than might be initially apparent between style manipulation (even creation?) and composable UI

I've been thinking about this too. In the GH issue on my repo,
@westnordost
brought up the use case of scripts that generate styles, and the (then) data class based API potentially being useful for that. I thought I was losing that utility when moving to composable style manipulation, but if the style composition can somehow be decoupled from the map SDK itself, perhaps this composable work can be used in style JSON generation scripts too? In pure kotlin multiplatform + compose runtime, no platform specific backing code (edited)
✅
1

Ian Wagner
Nov 12th, 2024 at 6:21 PM

Yes, we currently use IDs for interaction in the SwiftUI DSL: https://github.com/maplibre/swiftui-dsl/blob/main/Sources/MapLibreSwiftUI/Examples/Gestures.swift.

At the moment, it would be more trouble than it’s worth (IMO) to come up with a non-ID solution. The low-level library only knows about layer IDs. It doesn’t know about our higher-level layer structs (which just get lowered into the native types and only exist during the SwiftUI equivalent of the recomposition cycle).

sargunv
Nov 12th, 2024 at 6:24 PM

Interesting, so you directly pass user-provided IDs to the SDK? I'm not familiar with SwiftUI's equivalent to the recomposition cycle, but did you have to consider the potential edge case I discussed above? And if so, how did you work around it? (something like the multi-phase solution described above perhaps?)

I think I should try building a repro of this theoretical edge case; maybe I'm wrong about it being a problem at all

Ian Wagner
Nov 12th, 2024 at 6:25 PM

if the style composition can somehow be decoupled from the map SDK itself, perhaps this composable work can be used in style JSON generation scripts too? In pure kotlin multiplatform + compose runtime, no platform specific backing code

Yes, I think it can 🙂

MapLibre Native btw is pretty good about doing “incremental” updates to your styles. So I think this can just be a remember { … }-style thing at least initially. In SwiftUI, we do take some steps to prevent redoing all user layers every “recomposition” loop, and the result is quite good both in look (animating layer changes etc.) and performance.

sargunv
Nov 12th, 2024 at 6:28 PM

In SwiftUI, we do take some steps to prevent redoing all user layers every “recomposition” loop

ditto, that's the purpose of the keys in my API rn, though I could easily just key on id if I end up with user-provided ids

MapLibre Native btw is pretty good about doing “incremental” updates to your styles.

Ah, so if I insert a layer with an id that already exists, the native sdk will silently replace it? That's interesting if so, though I don't think it solves the issue as I'd still need to ensure not to then remove when the other node is removed from the tree

Ian Wagner
Nov 12th, 2024 at 6:33 PM

did you have to consider the potential edge case I discussed above

Do you mean the case of the user creating multiple layers with the same (manually specified) ID?

Or the bit about your own “recomposition” checks at the style layer to ensure that there aren’t needless changes applied to the map? We plan do something like the latter. But we don’t yet, because we do not (yet) have a good way of determining what requires a layer update. We have most of that in place though, and it’s performant enough with the MapLibre native APIs.

The user currently does have to supply an ID in our approach (which we use sort of like your key to determine changes that need to be made), but most operations involving sources and layers reference the Swift layer object directly; not the ID.

Doing a fully selective update of the MapLibre style is in the plans, but it’s just not worth the effort at the moment, at least on iOS.

6:33

though I could easily just key on id if I end up with user-provided ids

Yeah, our messages crossed but that’s a succinct description of what we do 😛

6:35

Ah, so if I insert a layer with an id that already exists, the native sdk will silently replace it?

No. But if you delete a layer and then add one with the same ID at the same z-order and the properties are very similar, it will behave as if you animated a change to a property. I don’t actually know what it does to accomplish this internally, but our energy profiling, framerate on devices, etc. is so good even with pretty complex styles that it’s not a concern for us at the moment.
6:37

Like check out this animated GIF on the repo README: https://github.com/maplibre/swiftui-dsl. That’s literally me making a source change, SwiftUI “recomposing” the style by dropping all user (composable) layers, and recreating them with different parameters. And it’s pretty efficient and even animates the change to line width.

We didn’t have to do any special “optimization” of our MapLibre API calls; just nuke user layers and rebuild.

6:39

Here’s our updateLayers function: https://github.com/maplibre/swiftui-dsl/blob/c406d80768ea4072f49d76b28bf4fc470f6397d0/Sources/MapLibreSwiftUI/MapViewCoordinator.swift#L223. It’s pretty naïve.

It gets called whenever the inputs change (like triggering a recomposition in Compose due to an observed property changing).

sargunv
Nov 12th, 2024 at 6:42 PM

Do you mean the case of the user creating multiple layers with the same (manually specified) ID?

I mean something along the lines of:

if (condition)
  Layer(id="example", source=foo)
else
  Layer(id="example", source=bar)

When condition changes from false to true or vice versa, one layer node will be added and another will be removed. But if the execution order results in adding before removing, then we've added the same layer id twice. I'm not sure if this example exactly would repro it but I suspect there are viable repros.

But if you delete a layer and then add one with the same ID at the same z-order and the properties are very similar, it will behave as if you animated a change to a property.

That's pretty cool! In my case if just the layer paint/layout properties change, I call a setter on the layer instead of removing/adding it. And I've noticed the animations provided by default. But if a constructor param changes (id, source, etc) then I remove/add it.

SwiftUI “recomposing” the style by dropping all user (composable) layers, and recreating them with different parameters. And it’s pretty efficient and even animates the change to line width.

Oh wow, I never considered dropping all user layers and reinserting them on every composition. But it sounds like that would get around the theoretical edge case (it's essentially a version of the "separate phase" solution I described) (edited)

6:43

Thanks for the code links! will check it out later tonight

Ian Wagner
Nov 12th, 2024 at 7:05 PM
Sure thing!

In my case if just the layer paint/layout properties change, I call a setter on the layer instead of removing/adding it. And I’ve noticed the animations provided by default. But if a constructor param changes (id, source, etc) then I remove/add it.

Yeah, I think that’s probably the “correct” solution. I just haven’t gotten around to it for SwiftUI since it’s never been an issue so far 😉

sargunv
Nov 12th, 2024 at 9:49 PM

Okay I’ve tried switching to user-provided layer IDs, and did indeed repro the issue with this construct:

if (bool) LineLayer(key = "tracks", source = trackSource)
CircleLayer(key = "stations", source = stationSource)
if (!bool) LineLayer(key = "tracks", source = trackSource)

Going to investigate a separate phase to remove/insert layers after composition

sargunv
Nov 12th, 2024 at 10:34 PM
I tried your approach of removing all layers and re-adding them in the proper order. While the iOS SDK handles this well as you said, the Android SDK raises an exception if I remove a layer and immediately re-add one with the same ID: “CannotAddLayerException: Cannot add layer twice”. Not sure why, as I’m printing the layer ids and confirming the id I’m about to add is no longer in the style
👀
1

Ian Wagner
Nov 12th, 2024 at 10:54 PM
Interesting! Probably worth opening a bug report for that with a minimal example.

sargunv
Nov 12th, 2024 at 10:58 PM
I’ve figured it out. On iOS I call the SDK’s removeLayer with a Layer reference, but on Android I call the SDK’s removeLayer with an id. Switching to a reference on Android resolves the problem

Will open a bug report soon

11:00

Separate, unrelated issue, I’m toggling my bool condition every ~second to test the repro, and toggling layers repeatedly like that seems to be causing OOMing on Android. iOS doesn’t have the same problem

Ian Wagner
Nov 12th, 2024 at 11:03 PM
Guess perhaps the Obj-C layer is a bit more helpful… weird that something as infrequent as every second would go OOM though; must be leaking or something. You can OOM pretty quickly if you create a bunch of map views and don’t clean them up. (Years ago, back when I built stuff with the Mapbox SDK, I realized they never intended you to have more than one instance; none of the resources are shared, so if you have a navigation stack-based app, you’d run out of memory about 5 maps in on the iPhones of the era 😂)

sargunv
Nov 12th, 2024 at 11:06 PM
oh no lol, I was actually planning on creating a navigation stack based app 😅

Ian Wagner
Nov 12th, 2024 at 11:08 PM
I’m not sure if MapLibre still has the same problem, but we ended up writing some code that told the map view to unload all (reasonable) resources. Then on re-appear we’d reload and reconstruct the prev. map state 😅

It’s only a problem if you have a navigation stack and you’ve got a map in the background eating up RAM. I think there are some newer methods to make it slim down its resource usage, but yeah… something to watch out for, esp. if you will be having multiple views in the stack with maps.
✅
1

sargunv
Nov 12th, 2024 at 11:08 PM
re: ooming, yeah most likely a leak somewhere. I logs from “scudo” like “Can’t populate more pages for size class X”, with ever increasing X, until eventually it crashes

[sargunv]

The Canvas mentioned in the OP is copied here in full:

---

Recently, I pushed a prototype of my MapLibre Compose Multiplatform wrapper that included a custom Composition to construct and manage the map style. This composition allows you to declare style Sources and Layers as Composables. The design decisions made for the prototype were really just whatever was convenient to get something working, but now I’d like to think through a proper approach for this foundational bit of the API. In particular, the questions I want to answer are:

• Should Source and Layer IDs be managed by the user (and passed in as a parameter to the Composable) or should they be managed automatically by the library?
• Which style Composables should emit a node in a tree, and which should return a value? (doing both is disallowed by the compose API guidelines)
• How are Sources connected to Layers? (ID string passed to the layer? Opaque “source handle“ passed to the layer? Parent node in the composition tree? LocalProvider and a lambda?

Compose background

Compose UI is a declarative UI framework for Android and other platforms. For the purpose of a map style, “Compose” here refers to the Compose Runtime, a platform-independent Kotlin compiler plugin and library. The Compose Runtime can be used to manage anything that can be represented as a tree; not necessarily just UI. I’m using it to manage a map style, as part of my Compose UI wrapper for the MapLibre SDK.
A Composable function can either emit a “node” to a tree, or it can return a value. If it returns a value, that value is usually eventually used as an input to a composable that emits a node. As the composition changes (due to changes in state triggering recomposition), so does the resulting tree.

Current status (or, “whatever was convenient”)

Here’s a simplified example what it looks like to use my library today:

// MapibreMap is a Compose UI composable
MaplibreMap(styleUrl = style) {
  // This block is no longer in the UI composition; it's in our Style composition

  // At the top level we can define Sources (as children of the Style)
  GeoJsonUrlSource(dataUrl = Res.getUri(...)) { amtrakRoutes ->

    // Layers are children of Sources
    LineLayer(
      source = amtrakRoutes,
      paint = LinePaint(
        lineWidth = interpolate(exponential(const(2)), zoom(), 0 to const(2), 10 to const(4)),
      ),
    )
    
    // Optionally, Layers are children of AnchoredLayers, which define how to insert their
    // layers into the base style. Here we're inserting below layer ID "labels".
    AnchoredLayers(Anchor.Below("labels")) {
      LineLayer( ... )
    }
  }
}

This implementation, regarding the above questions, answers with:

• Source and Layer IDs are automatically managed by the library (as incrementing ints) and hidden from the user.
• Sources, Layers, and AnchoredLayer groups all emit nodes in the composition tree. None return values.
• Sources take a lambda, which has as a parameter an opaque “source handle” wrapped around an ID, which is passed to children layers to connect them to sources.

The tree produced by this implementation looks like:

StyleNode
├── SourceNode
    ├── LayerNode
    └── AnchoredLayersNode // (below(labels))
        └── LayerNode
    └── AnchoredLayersNode // (below(labels))
        └── LayerNode

This implementation has a number of problems:

• Any exceptions or errors referencing a source or layer ID won’t tell the user which source or layer is problematic.
• Related layers that consume different sources (say, a circle layer for train stations and a line layer for train routes) are defined far from each other (because they’re contained by their respective sources).
  • As a consequence of this, they’ll be under duplicate AnchoredLayers nodes, which will compete when inserting their first (“anchor”) layer.
• Nodes included conditionally don’t have any sort of key for Compose to identify them by default, so Compose may do extra work to recreate all layers defined after a layer is added/removed from the beginning of a list of layers (unless the user realizes this and wraps each one in a key block.
  • Since some parameters of sources and layers aren’t mutable, in many cases these recompositions will result in removing and re-adding sources and layers to the style.
• Compose builds a tree either bottom up or top down. If we build top down, we’ll insert sources before their dependent layers (good) but also remove sources before their dependent layers (bad). If we build bottom up, we have the same problem in reverse (on insertion instead of on removal)

Solving the problems with API changes

Starting with the source/layer insertion/removal order, as that’s the only broken functionality in the current implementation. The rest is a performance issue or a usability issue. This problem is rooted in that a Source is really a resource used by Layers, and it has no “location” in the style tree. So, the API should make Source composables that provider some reference to a Source without the Source to the tree. To ensure Sources get added and removed from the style when Layers that reference them are, the style management code should reference count Sources and insert to the style when the count goes from 0 to 1, and remove from the style when 1 to 0.
Our tree now looks like:

StyleNode // anchor top
├── LayerNode
├── AnchoredLayersNode // (anchor below "labels")
│   └── LayerNode
└── AnchoredLayersNode // (anchor below "labels")
    └── LayerNode

To prevent duplicate anchors from competing with each other, we can make AnchoredLayers also not emit a node, but rather just wrap a lambda with a LocalProvider for an Anchor. Similar to source reference counting, the style manager can create a group of anchored layers when it sees a new, unique anchor, and remove it when the group is empty. The “tree” now looks like this:

StyleNode
├── LayerNode // anchor top
├── LayerNode // anchor below "labels"
└── LayerNode // anchor below "labels"

Well, our “tree” is now just a list, as the only Composables emitting nodes are Layers, and they have no children. This gives us a clue to solve our issue of too much recomposition when some layers are conditional. When you create a list in Compose UI, you pass a key to the LazyColumn so you can add/remove list items anywhere in the list, and only the affected items will recompose. Sources and layers already have an ID, so let’s stop managing them automatically, and instead ask the user to pass id explicitly. We can inline the function and use the id as a key.

LineLayer(id = "foo", ...)

Our problems are solved... mostly. Consider the case when an immutable property (like tolerance) of a source changes. We need to instantiate a new source, and since the user passed a constant id, the new source has the same id as the old one. Consider what happens if there’s multiple layers referencing the same source. The first layer recomposes to reference the new source. Since the second layer is still using it, the reference count of the old source stays above zero. The count for the new source increments to 1, and the new source is inserted into the style with the same id as the old. Two sources with the same ID are not allowed in a Maplibre style.
We can solve this easily by reference counting source ids instead of actual Source objects, and having layers reference just the IDs (that’s what they reference in the JSON after all). But now what happens if a user declares the same source id twice? The first will get silently replaced by the second (because the style manager can’t tell the difference between that and a recompose of the old source). And if the sources were defined far apart, this might be a difficult bug to track down. So, let’s go back to automatically managing unique source and layer IDs with an incrementing integer, but to make error messages more clear, let’s concatenate these unique IDs with the user’s provided id. To avoid confusion between the id provided by the user and the actual ID set in the style, we’ll rename the user’s parameter to key. And it’ll still be doing the job of a key, preventing extraneous recompositions.

LineLayer(key = "foo", ...)

Finally, a mock up of what using the API looks like after the above changes, and Composable naming updated to match the Compose style guidelines:

MaplibreMap(styleUrl = style) {
  val amtrakRoutes = rememberGeoJsonUrlSource(key = "amtrakRoutes", dataUrl = Res.getUri(...))
  
  LineLayer(
    key = "amtrakRoutes-outline",
    source = amtrakRoutes,
    paint = LinePaint(
      lineWidth = interpolate(exponential(const(2)), zoom(), 0 to const(2), 10 to const(4)),
    ),
  )

  AnchoredLayers(Anchor.Below("labels")) {
    LineLayer( ... )
  }
}