v2: refactor: new Canvas, Compositor, and Layer API

[aymanbagabas]

This change redefines what a Canvas and Layer are within the lipgloss
package. The Canvas is now a simple screen buffer that can compose
layers and drawable types.

A layer now doesn't do any computation and only represents a tree node. Using a compositor flattens a list of layers, and is able to draw them or render them into a string.

[andreynering]

[lrstanley]

I have some concerns with the layer functionality, not necessarily specific to this PR (as it was present with the previous version in v2-exp as well). There are a couple of things on layers that I feel like are too easy to accidentally misconfigure, primarily around recursive child layers.

• Setting dimensional information at function execution time vs at render time. e.g., layer.X(val) directly mutates child layers at function call time, but this means that if that child layer is mutated after the fact, the changes in the X() call are lost. It may be worth storing that info only on the layer that is being changed, then either doing the actual recursive child corrections to coordinates in Render, or a separate step of some kind. This also looks like it may apply to AddLayers() as well, where, depending on when it's executed, it may produce the wrong offset information.
  • Would it be worth, rather than mutating the child, to store a reference to the parent in the child when it's added to a parent, so if the parent exists, it can recurse up the tree to get the information it needs?
• What is the impact of calling something like X(val), but it only affects direct children, vs children of children, and so on?
• functions like GetLayer(id) only check 1 level deep. Should it be recursive for all children?
• What is the expected outcome when a child 2 levels deep has a higher z-index than something else? It's currently rendered in order of z-index at the top level, but it seems like undefined (or unclear) behavior when children have different Z levels (in addition to the fact that someone can add a layer, then change the Z value, and there is no warning/recommendation against this currently).

[aymanbagabas]

I have some concerns with the layer functionality, not necessarily specific to this PR (as it was present with the previous version in v2-exp as well). There are a couple of things on layers that I feel like are too easy to accidentally misconfigure, primarily around recursive child layers.

• Setting dimensional information at function execution time vs at render time. e.g., layer.X(val) directly mutates child layers at function call time, but this means that if that child layer is mutated after the fact, the changes in the X() call are lost. It may be worth storing that info only on the layer that is being changed, then either doing the actual recursive child corrections to coordinates in Render, or a separate step of some kind. This also looks like it may apply to AddLayers() as well, where, depending on when it's executed, it may produce the wrong offset information.

  • Would it be worth, rather than mutating the child, to store a reference to the parent in the child when it's added to a parent, so if the parent exists, it can recurse up the tree to get the information it needs?

• What is the impact of calling something like X(val), but it only affects direct children, vs children of children, and so on?

• functions like GetLayer(id) only check 1 level deep. Should it be recursive for all children?

• What is the expected outcome when a child 2 levels deep has a higher z-index than something else? It's currently rendered in order of z-index at the top level, but it seems like undefined (or unclear) behavior when children have different Z levels (in addition to the fact that someone can add a layer, then change the Z value, and there is no warning/recommendation against this currently).

Good points you raise here. I've made some changes, with the help of Crush, to work around these concerns. Let me know if you see any other issues 🙂

[lrstanley]

Good points you raise here. I've made some changes, with the help of Crush, to work around these concerns. Let me know if you see any other issues 🙂

I mentioned this in Discord as well, but an alternative, and I think a bit cleaner approach could be used. See my version of addressing those concerns here.

Some addl. notes on my proposed tweaks:

• I also store the width/height pre-computed, otherwise it will get computed more than 2+ times, depending on what the user is doing, and those functions are very compute heavy
• return a pointer on Compose so you can chain it with .Render()
• add MaxZ() which is needed to be able to wrap other layers, otherwise you can't easily enforce a situation where you want something to always be on top of something else, given you can't access the children from the parent.
• add String(), which prints out a debug-friendly version of all of the layers, indented based on depth

I'm still working on a layout wrapper PoC to create more complex layouts, so I will keep poking things to see where any gaps might be/may make some follow up PRs.

[lrstanley]

Some minor tweaks that may be worth looking at:

1. remove absolute Z functionality, as I don't think this will work how people expect it would.
   • This was causing the following to be rendered behind other lower z layers: https://cdn.liam.sh/share/2025/11/layers.txt (last layer in this go-spew output should be on top)
   • see also: https://cdn.liam.sh/share/2025/11/explorer_GQ10NjdU0j.mp4
   • maybe there is still a usecase for absolute z that I can't think of, so maybe it should be configurable on the compositor?
     • E.g. (c *Compositor) UseAbsoluteZ(bool). Alternatively, on *Layer, we could also do (l *Layer) CompoundingZ(int), which sets both a z field, in addition to an compoundingZ field, and if that is present, it's always added onto children?
2. Allow lipgloss.Canvas to be reused, for users who would like higher perf.

Patch for the above: https://cdn.liam.sh/share/2025/11/misc-v2-canvas-1.patch

$ curl -sL https://cdn.liam.sh/share/2025/11/misc-v2-canvas-1.patch | git apply