@driftengine/ui2d 4.6.1 → 4.7.1

package/README.md

@@ -48,6 +48,12 @@ the time, so they are named separately and each says which it is.
 A `Camera2D` is where it is, how far in (`zoom`, in pixels per world unit) and which way up
 (`rotation`, radians, anticlockwise). Turning the camera turns the world the other way.
 
+**A picture keeps its top up in both.** A frame's top row is drawn at the top of the sprite whichever
+way y counts, because the vertex stage reads the affine's orientation and turns the frame's rows to
+match. It did not until 2026-10-02: every sprite and tile drawn through `worldToNdc` came out upside
+down, and `scripts/sprite-check.mjs`, which checked screen space only, passed. It draws the same
+rectangles in a world now and asserts the frame is byte for byte the one screen space draws.
+
 ## Order is the layering
 
 There is no depth here, on purpose: a sprite writes no depth and tests none, so **the order sprites
@@ -178,6 +184,18 @@ interface tree is tens of nodes built once and mutated, not thousands rebuilt pe
 The box you give it is what is _available_ — the root resolves its own size against it, so the same
 call lays out a full-screen HUD and a tooltip.
 
+## Clipping and scrolling
+
+A node made with `clip: true` bounds what its descendants draw and where they can be pointed at.
+`drawUiTree` cuts every quad under it to the rectangle its clipping ancestors leave, an image's frame
+in proportion, and hands the sink that visible rectangle so a caller can cut its text the same way;
+`uiHitTest` finds nothing outside it. A clipping node's `scrollX` and `scrollY` move its children
+under it at layout, and `routeScrollWheel`, `scrollBy` and `clampScroll` move them within
+`scrollExtent`. **Until 2026-10-02 the clip was laid out and scrolled and nothing drew it**: a list's
+rows drew wherever they had scrolled to, and a row scrolled below the list still took the pointer
+there. It is cut on the CPU rather than by a scissor, which is state a contributed pass would have to
+set and restore on both backends.
+
 ## Hit testing, focus and routing
 
 `uiHitTest` searches **last-drawn first**, so it agrees with the picture. **A node that is not
@@ -195,7 +213,7 @@ node hidden since it was focused does not take the keyboard with it.
 
 **Text is the caller's.** This package draws quads; core already draws two kinds of text. Pass a
 `UiContentSink` to `drawUiTree` and it hands you every node with text at its resolved rect, in the
-order it was drawn.
+order it was drawn, with the part of it a clip leaves visible.
 
 ## From DriftScript
 

package/dist/shaders/generated/sprite.wgsl.d.ts

@@ -1,5 +1,5 @@
 export declare const SPRITE_FRAG_WGSL = "struct Uniforms {\n    uOutputTransform: i32,\n    uOutputExposure: f32,\n}\n\n@group(0) @binding(1) \nvar<uniform> unnamed: Uniforms;\n@group(0) @binding(32) \nvar uSpriteTexture_t: texture_2d<f32>;\n@group(0) @binding(33) \nvar uSpriteTexture_s: sampler;\nvar<private> vUv_1: vec2<f32>;\nvar<private> vTint_1: vec4<f32>;\nvar<private> fragColor: vec4<f32>;\n\nfn linearToSrgb_u0028_vf3_u003b(c: ptr<function, vec3<f32>>) -> vec3<f32> {\n    var low: vec3<f32>;\n    var high: vec3<f32>;\n\n    let _e55 = (*c);\n    low = (_e55 * 12.92f);\n    let _e57 = (*c);\n    high = ((pow(max(_e57, vec3<f32>(0f, 0f, 0f)), vec3<f32>(0.41666666f, 0.41666666f, 0.41666666f)) * 1.055f) - vec3(0.055f));\n    let _e63 = high;\n    let _e64 = low;\n    let _e65 = (*c);\n    return mix(_e63, _e64, step(_e65, vec3<f32>(0.0031308f, 0.0031308f, 0.0031308f)));\n}\n\nfn rrtAndOdtFit_u0028_vf3_u003b(v: ptr<function, vec3<f32>>) -> vec3<f32> {\n    var a: vec3<f32>;\n    var b: vec3<f32>;\n\n    let _e55 = (*v);\n    let _e56 = (*v);\n    a = ((_e55 * (_e56 + vec3(0.0245786f))) - vec3(0.000090537f));\n    let _e62 = (*v);\n    let _e63 = (*v);\n    b = ((_e62 * ((_e63 * 0.983729f) + vec3(0.432951f))) + vec3(0.238081f));\n    let _e70 = a;\n    let _e71 = b;\n    return (_e70 / _e71);\n}\n\nfn acesFilmic_u0028_vf3_u003b(x: ptr<function, vec3<f32>>) -> vec3<f32> {\n    var param: vec3<f32>;\n\n    let _e55 = unnamed.uOutputExposure;\n    let _e56 = (*x);\n    (*x) = (_e56 * _e55);\n    let _e58 = (*x);\n    param = (mat3x3<f32>(vec3<f32>(0.59719f, 0.076f, 0.0284f), vec3<f32>(0.35458f, 0.90834f, 0.13383f), vec3<f32>(0.04823f, 0.01566f, 0.83777f)) * _e58);\n    let _e60 = rrtAndOdtFit_u0028_vf3_u003b((&param));\n    return clamp((mat3x3<f32>(vec3<f32>(1.60475f, -0.10208f, -0.00327f), vec3<f32>(-0.53108f, 1.10813f, -0.07276f), vec3<f32>(-0.07367f, -0.00605f, 1.07602f)) * _e60), vec3(0f), vec3(1f));\n}\n\nfn applyOutputTransform_u0028_vf3_u003b(c_1: ptr<function, vec3<f32>>) -> vec3<f32> {\n    var param_1: vec3<f32>;\n    var param_2: vec3<f32>;\n\n    let _e56 = unnamed.uOutputTransform;\n    if (_e56 == 0i) {\n        let _e58 = (*c_1);\n        return _e58;\n    }\n    let _e60 = unnamed.uOutputTransform;\n    if (_e60 == 2i) {\n        let _e62 = (*c_1);\n        param_1 = _e62;\n        let _e63 = acesFilmic_u0028_vf3_u003b((&param_1));\n        (*c_1) = _e63;\n    }\n    let _e64 = (*c_1);\n    param_2 = _e64;\n    let _e65 = linearToSrgb_u0028_vf3_u003b((&param_2));\n    return _e65;\n}\n\nfn main_1() {\n    var texel: vec4<f32>;\n    var colour: vec4<f32>;\n    var param_3: vec3<f32>;\n\n    let _e55 = vUv_1;\n    let _e56 = textureSample(uSpriteTexture_t, uSpriteTexture_s, _e55);\n    texel = _e56;\n    let _e57 = texel;\n    let _e58 = vTint_1;\n    colour = (_e57 * _e58);\n    let _e61 = colour[3u];\n    if (_e61 < 0.00392157f) {\n        discard;\n    }\n    let _e63 = colour;\n    param_3 = _e63.xyz;\n    let _e65 = applyOutputTransform_u0028_vf3_u003b((&param_3));\n    let _e66 = colour;\n    colour = vec4<f32>(_e65.x, _e65.y, _e65.z, _e66.w);\n    let _e72 = colour;\n    let _e75 = colour[3u];\n    let _e76 = (_e72.xyz * _e75);\n    let _e78 = colour[3u];\n    fragColor = vec4<f32>(_e76.x, _e76.y, _e76.z, _e78);\n    return;\n}\n\n@fragment \nfn main(@location(0) vUv: vec2<f32>, @location(1) vTint: vec4<f32>) -> @location(0) vec4<f32> {\n    vUv_1 = vUv;\n    vTint_1 = vTint;\n    main_1();\n    let _e5 = fragColor;\n    return _e5;\n}\n";
-export declare const SPRITE_VERT_WGSL = "struct Uniforms {\n    uToNdc0_: vec4<f32>,\n    uToNdc1_: vec4<f32>,\n    uClipCorrection: mat4x4<f32>,\n}\n\nstruct gl_PerVertex {\n    @builtin(position) gl_Position: vec4<f32>,\n    gl_PointSize: f32,\n}\n\nstruct VertexOutput {\n    @location(0) member: vec2<f32>,\n    @location(1) member_1: vec4<f32>,\n    @builtin(position) gl_Position: vec4<f32>,\n}\n\nvar<private> gl_VertexIndex_1: i32;\nvar<private> aOrigin_1: vec2<f32>;\nvar<private> aEdges_1: vec4<f32>;\n@group(0) @binding(0) \nvar<uniform> unnamed: Uniforms;\nvar<private> vUv: vec2<f32>;\nvar<private> aUv_1: vec4<f32>;\nvar<private> vTint: vec4<f32>;\nvar<private> aTint_1: vec4<f32>;\nvar<private> unnamed_1: gl_PerVertex = gl_PerVertex(vec4<f32>(0f, 0f, 0f, 1f), 1f);\n\nfn main_1() {\n    var corner: vec2<f32>;\n    var indexable: array<vec2<f32>, 6>;\n    var p: vec2<f32>;\n    var ndc: vec2<f32>;\n\n    let _e28 = gl_VertexIndex_1;\n    indexable = array<vec2<f32>, 6>(vec2<f32>(0f, 0f), vec2<f32>(1f, 0f), vec2<f32>(0f, 1f), vec2<f32>(0f, 1f), vec2<f32>(1f, 0f), vec2<f32>(1f, 1f));\n    let _e30 = indexable[_e28];\n    corner = _e30;\n    let _e31 = aOrigin_1;\n    let _e32 = aEdges_1;\n    let _e35 = corner[0u];\n    let _e38 = aEdges_1;\n    let _e41 = corner[1u];\n    p = ((_e31 + (_e32.xy * _e35)) + (_e38.zw * _e41));\n    let _e46 = unnamed.uToNdc0_[0u];\n    let _e48 = p[0u];\n    let _e52 = unnamed.uToNdc0_[2u];\n    let _e54 = p[1u];\n    let _e59 = unnamed.uToNdc1_[0u];\n    let _e63 = unnamed.uToNdc0_[1u];\n    let _e65 = p[0u];\n    let _e69 = unnamed.uToNdc0_[3u];\n    let _e71 = p[1u];\n    let _e76 = unnamed.uToNdc1_[1u];\n    ndc = vec2<f32>((((_e46 * _e48) + (_e52 * _e54)) + _e59), (((_e63 * _e65) + (_e69 * _e71)) + _e76));\n    let _e79 = aUv_1;\n    let _e81 = aUv_1;\n    let _e83 = corner;\n    vUv = mix(_e79.xy, _e81.zw, _e83);\n    let _e85 = aTint_1;\n    vTint = _e85;\n    let _e87 = unnamed.uClipCorrection;\n    let _e88 = ndc;\n    unnamed_1.gl_Position = (_e87 * vec4<f32>(_e88.x, _e88.y, 0f, 1f));\n    return;\n}\n\n@vertex \nfn main(@builtin(vertex_index) gl_VertexIndex: u32, @location(3) aOrigin: vec2<f32>, @location(0) aEdges: vec4<f32>, @location(1) aUv: vec4<f32>, @location(2) aTint: vec4<f32>) -> VertexOutput {\n    gl_VertexIndex_1 = i32(gl_VertexIndex);\n    aOrigin_1 = aOrigin;\n    aEdges_1 = aEdges;\n    aUv_1 = aUv;\n    aTint_1 = aTint;\n    main_1();\n    let _e16 = unnamed_1.gl_Position.y;\n    unnamed_1.gl_Position.y = -(_e16);\n    let _e18 = vUv;\n    let _e19 = vTint;\n    let _e20 = unnamed_1.gl_Position;\n    return VertexOutput(_e18, _e19, _e20);\n}\n";
+export declare const SPRITE_VERT_WGSL = "struct Uniforms {\n    uToNdc0_: vec4<f32>,\n    uToNdc1_: vec4<f32>,\n    uClipCorrection: mat4x4<f32>,\n}\n\nstruct gl_PerVertex {\n    @builtin(position) gl_Position: vec4<f32>,\n    gl_PointSize: f32,\n}\n\nstruct VertexOutput {\n    @location(0) member: vec2<f32>,\n    @location(1) member_1: vec4<f32>,\n    @builtin(position) gl_Position: vec4<f32>,\n}\n\nvar<private> gl_VertexIndex_1: i32;\nvar<private> aOrigin_1: vec2<f32>;\nvar<private> aEdges_1: vec4<f32>;\n@group(0) @binding(0) \nvar<uniform> unnamed: Uniforms;\nvar<private> vUv: vec2<f32>;\nvar<private> aUv_1: vec4<f32>;\nvar<private> vTint: vec4<f32>;\nvar<private> aTint_1: vec4<f32>;\nvar<private> unnamed_1: gl_PerVertex = gl_PerVertex(vec4<f32>(0f, 0f, 0f, 1f), 1f);\n\nfn main_1() {\n    var corner: vec2<f32>;\n    var indexable: array<vec2<f32>, 6>;\n    var p: vec2<f32>;\n    var ndc: vec2<f32>;\n    var orientation: f32;\n    var along: vec2<f32>;\n    var local: f32;\n\n    let _e31 = gl_VertexIndex_1;\n    indexable = array<vec2<f32>, 6>(vec2<f32>(0f, 0f), vec2<f32>(1f, 0f), vec2<f32>(0f, 1f), vec2<f32>(0f, 1f), vec2<f32>(1f, 0f), vec2<f32>(1f, 1f));\n    let _e33 = indexable[_e31];\n    corner = _e33;\n    let _e34 = aOrigin_1;\n    let _e35 = aEdges_1;\n    let _e38 = corner[0u];\n    let _e41 = aEdges_1;\n    let _e44 = corner[1u];\n    p = ((_e34 + (_e35.xy * _e38)) + (_e41.zw * _e44));\n    let _e49 = unnamed.uToNdc0_[0u];\n    let _e51 = p[0u];\n    let _e55 = unnamed.uToNdc0_[2u];\n    let _e57 = p[1u];\n    let _e62 = unnamed.uToNdc1_[0u];\n    let _e66 = unnamed.uToNdc0_[1u];\n    let _e68 = p[0u];\n    let _e72 = unnamed.uToNdc0_[3u];\n    let _e74 = p[1u];\n    let _e79 = unnamed.uToNdc1_[1u];\n    ndc = vec2<f32>((((_e49 * _e51) + (_e55 * _e57)) + _e62), (((_e66 * _e68) + (_e72 * _e74)) + _e79));\n    let _e84 = unnamed.uToNdc0_[0u];\n    let _e87 = unnamed.uToNdc0_[3u];\n    let _e91 = unnamed.uToNdc0_[1u];\n    let _e94 = unnamed.uToNdc0_[2u];\n    orientation = ((_e84 * _e87) - (_e91 * _e94));\n    let _e98 = corner[0u];\n    let _e99 = orientation;\n    if (_e99 > 0f) {\n        let _e102 = corner[1u];\n        local = (1f - _e102);\n    } else {\n        let _e105 = corner[1u];\n        local = _e105;\n    }\n    let _e106 = local;\n    along = vec2<f32>(_e98, _e106);\n    let _e108 = aUv_1;\n    let _e110 = aUv_1;\n    let _e112 = along;\n    vUv = mix(_e108.xy, _e110.zw, _e112);\n    let _e114 = aTint_1;\n    vTint = _e114;\n    let _e116 = unnamed.uClipCorrection;\n    let _e117 = ndc;\n    unnamed_1.gl_Position = (_e116 * vec4<f32>(_e117.x, _e117.y, 0f, 1f));\n    return;\n}\n\n@vertex \nfn main(@builtin(vertex_index) gl_VertexIndex: u32, @location(3) aOrigin: vec2<f32>, @location(0) aEdges: vec4<f32>, @location(1) aUv: vec4<f32>, @location(2) aTint: vec4<f32>) -> VertexOutput {\n    gl_VertexIndex_1 = i32(gl_VertexIndex);\n    aOrigin_1 = aOrigin;\n    aEdges_1 = aEdges;\n    aUv_1 = aUv;\n    aTint_1 = aTint;\n    main_1();\n    let _e16 = unnamed_1.gl_Position.y;\n    unnamed_1.gl_Position.y = -(_e16);\n    let _e18 = vUv;\n    let _e19 = vTint;\n    let _e20 = unnamed_1.gl_Position;\n    return VertexOutput(_e18, _e19, _e20);\n}\n";
 /**
  * What the transform assigned, so the renderer binds the same numbers.
  *

package/dist/shaders/generated/sprite.wgsl.js

@@ -5,7 +5,7 @@
  * the next generation, and `npm run wgsl:check` fails the build when this is stale.
  */
 export const SPRITE_FRAG_WGSL = "struct Uniforms {\n    uOutputTransform: i32,\n    uOutputExposure: f32,\n}\n\n@group(0) @binding(1) \nvar<uniform> unnamed: Uniforms;\n@group(0) @binding(32) \nvar uSpriteTexture_t: texture_2d<f32>;\n@group(0) @binding(33) \nvar uSpriteTexture_s: sampler;\nvar<private> vUv_1: vec2<f32>;\nvar<private> vTint_1: vec4<f32>;\nvar<private> fragColor: vec4<f32>;\n\nfn linearToSrgb_u0028_vf3_u003b(c: ptr<function, vec3<f32>>) -> vec3<f32> {\n    var low: vec3<f32>;\n    var high: vec3<f32>;\n\n    let _e55 = (*c);\n    low = (_e55 * 12.92f);\n    let _e57 = (*c);\n    high = ((pow(max(_e57, vec3<f32>(0f, 0f, 0f)), vec3<f32>(0.41666666f, 0.41666666f, 0.41666666f)) * 1.055f) - vec3(0.055f));\n    let _e63 = high;\n    let _e64 = low;\n    let _e65 = (*c);\n    return mix(_e63, _e64, step(_e65, vec3<f32>(0.0031308f, 0.0031308f, 0.0031308f)));\n}\n\nfn rrtAndOdtFit_u0028_vf3_u003b(v: ptr<function, vec3<f32>>) -> vec3<f32> {\n    var a: vec3<f32>;\n    var b: vec3<f32>;\n\n    let _e55 = (*v);\n    let _e56 = (*v);\n    a = ((_e55 * (_e56 + vec3(0.0245786f))) - vec3(0.000090537f));\n    let _e62 = (*v);\n    let _e63 = (*v);\n    b = ((_e62 * ((_e63 * 0.983729f) + vec3(0.432951f))) + vec3(0.238081f));\n    let _e70 = a;\n    let _e71 = b;\n    return (_e70 / _e71);\n}\n\nfn acesFilmic_u0028_vf3_u003b(x: ptr<function, vec3<f32>>) -> vec3<f32> {\n    var param: vec3<f32>;\n\n    let _e55 = unnamed.uOutputExposure;\n    let _e56 = (*x);\n    (*x) = (_e56 * _e55);\n    let _e58 = (*x);\n    param = (mat3x3<f32>(vec3<f32>(0.59719f, 0.076f, 0.0284f), vec3<f32>(0.35458f, 0.90834f, 0.13383f), vec3<f32>(0.04823f, 0.01566f, 0.83777f)) * _e58);\n    let _e60 = rrtAndOdtFit_u0028_vf3_u003b((&param));\n    return clamp((mat3x3<f32>(vec3<f32>(1.60475f, -0.10208f, -0.00327f), vec3<f32>(-0.53108f, 1.10813f, -0.07276f), vec3<f32>(-0.07367f, -0.00605f, 1.07602f)) * _e60), vec3(0f), vec3(1f));\n}\n\nfn applyOutputTransform_u0028_vf3_u003b(c_1: ptr<function, vec3<f32>>) -> vec3<f32> {\n    var param_1: vec3<f32>;\n    var param_2: vec3<f32>;\n\n    let _e56 = unnamed.uOutputTransform;\n    if (_e56 == 0i) {\n        let _e58 = (*c_1);\n        return _e58;\n    }\n    let _e60 = unnamed.uOutputTransform;\n    if (_e60 == 2i) {\n        let _e62 = (*c_1);\n        param_1 = _e62;\n        let _e63 = acesFilmic_u0028_vf3_u003b((&param_1));\n        (*c_1) = _e63;\n    }\n    let _e64 = (*c_1);\n    param_2 = _e64;\n    let _e65 = linearToSrgb_u0028_vf3_u003b((&param_2));\n    return _e65;\n}\n\nfn main_1() {\n    var texel: vec4<f32>;\n    var colour: vec4<f32>;\n    var param_3: vec3<f32>;\n\n    let _e55 = vUv_1;\n    let _e56 = textureSample(uSpriteTexture_t, uSpriteTexture_s, _e55);\n    texel = _e56;\n    let _e57 = texel;\n    let _e58 = vTint_1;\n    colour = (_e57 * _e58);\n    let _e61 = colour[3u];\n    if (_e61 < 0.00392157f) {\n        discard;\n    }\n    let _e63 = colour;\n    param_3 = _e63.xyz;\n    let _e65 = applyOutputTransform_u0028_vf3_u003b((&param_3));\n    let _e66 = colour;\n    colour = vec4<f32>(_e65.x, _e65.y, _e65.z, _e66.w);\n    let _e72 = colour;\n    let _e75 = colour[3u];\n    let _e76 = (_e72.xyz * _e75);\n    let _e78 = colour[3u];\n    fragColor = vec4<f32>(_e76.x, _e76.y, _e76.z, _e78);\n    return;\n}\n\n@fragment \nfn main(@location(0) vUv: vec2<f32>, @location(1) vTint: vec4<f32>) -> @location(0) vec4<f32> {\n    vUv_1 = vUv;\n    vTint_1 = vTint;\n    main_1();\n    let _e5 = fragColor;\n    return _e5;\n}\n";
-export const SPRITE_VERT_WGSL = "struct Uniforms {\n    uToNdc0_: vec4<f32>,\n    uToNdc1_: vec4<f32>,\n    uClipCorrection: mat4x4<f32>,\n}\n\nstruct gl_PerVertex {\n    @builtin(position) gl_Position: vec4<f32>,\n    gl_PointSize: f32,\n}\n\nstruct VertexOutput {\n    @location(0) member: vec2<f32>,\n    @location(1) member_1: vec4<f32>,\n    @builtin(position) gl_Position: vec4<f32>,\n}\n\nvar<private> gl_VertexIndex_1: i32;\nvar<private> aOrigin_1: vec2<f32>;\nvar<private> aEdges_1: vec4<f32>;\n@group(0) @binding(0) \nvar<uniform> unnamed: Uniforms;\nvar<private> vUv: vec2<f32>;\nvar<private> aUv_1: vec4<f32>;\nvar<private> vTint: vec4<f32>;\nvar<private> aTint_1: vec4<f32>;\nvar<private> unnamed_1: gl_PerVertex = gl_PerVertex(vec4<f32>(0f, 0f, 0f, 1f), 1f);\n\nfn main_1() {\n    var corner: vec2<f32>;\n    var indexable: array<vec2<f32>, 6>;\n    var p: vec2<f32>;\n    var ndc: vec2<f32>;\n\n    let _e28 = gl_VertexIndex_1;\n    indexable = array<vec2<f32>, 6>(vec2<f32>(0f, 0f), vec2<f32>(1f, 0f), vec2<f32>(0f, 1f), vec2<f32>(0f, 1f), vec2<f32>(1f, 0f), vec2<f32>(1f, 1f));\n    let _e30 = indexable[_e28];\n    corner = _e30;\n    let _e31 = aOrigin_1;\n    let _e32 = aEdges_1;\n    let _e35 = corner[0u];\n    let _e38 = aEdges_1;\n    let _e41 = corner[1u];\n    p = ((_e31 + (_e32.xy * _e35)) + (_e38.zw * _e41));\n    let _e46 = unnamed.uToNdc0_[0u];\n    let _e48 = p[0u];\n    let _e52 = unnamed.uToNdc0_[2u];\n    let _e54 = p[1u];\n    let _e59 = unnamed.uToNdc1_[0u];\n    let _e63 = unnamed.uToNdc0_[1u];\n    let _e65 = p[0u];\n    let _e69 = unnamed.uToNdc0_[3u];\n    let _e71 = p[1u];\n    let _e76 = unnamed.uToNdc1_[1u];\n    ndc = vec2<f32>((((_e46 * _e48) + (_e52 * _e54)) + _e59), (((_e63 * _e65) + (_e69 * _e71)) + _e76));\n    let _e79 = aUv_1;\n    let _e81 = aUv_1;\n    let _e83 = corner;\n    vUv = mix(_e79.xy, _e81.zw, _e83);\n    let _e85 = aTint_1;\n    vTint = _e85;\n    let _e87 = unnamed.uClipCorrection;\n    let _e88 = ndc;\n    unnamed_1.gl_Position = (_e87 * vec4<f32>(_e88.x, _e88.y, 0f, 1f));\n    return;\n}\n\n@vertex \nfn main(@builtin(vertex_index) gl_VertexIndex: u32, @location(3) aOrigin: vec2<f32>, @location(0) aEdges: vec4<f32>, @location(1) aUv: vec4<f32>, @location(2) aTint: vec4<f32>) -> VertexOutput {\n    gl_VertexIndex_1 = i32(gl_VertexIndex);\n    aOrigin_1 = aOrigin;\n    aEdges_1 = aEdges;\n    aUv_1 = aUv;\n    aTint_1 = aTint;\n    main_1();\n    let _e16 = unnamed_1.gl_Position.y;\n    unnamed_1.gl_Position.y = -(_e16);\n    let _e18 = vUv;\n    let _e19 = vTint;\n    let _e20 = unnamed_1.gl_Position;\n    return VertexOutput(_e18, _e19, _e20);\n}\n";
+export const SPRITE_VERT_WGSL = "struct Uniforms {\n    uToNdc0_: vec4<f32>,\n    uToNdc1_: vec4<f32>,\n    uClipCorrection: mat4x4<f32>,\n}\n\nstruct gl_PerVertex {\n    @builtin(position) gl_Position: vec4<f32>,\n    gl_PointSize: f32,\n}\n\nstruct VertexOutput {\n    @location(0) member: vec2<f32>,\n    @location(1) member_1: vec4<f32>,\n    @builtin(position) gl_Position: vec4<f32>,\n}\n\nvar<private> gl_VertexIndex_1: i32;\nvar<private> aOrigin_1: vec2<f32>;\nvar<private> aEdges_1: vec4<f32>;\n@group(0) @binding(0) \nvar<uniform> unnamed: Uniforms;\nvar<private> vUv: vec2<f32>;\nvar<private> aUv_1: vec4<f32>;\nvar<private> vTint: vec4<f32>;\nvar<private> aTint_1: vec4<f32>;\nvar<private> unnamed_1: gl_PerVertex = gl_PerVertex(vec4<f32>(0f, 0f, 0f, 1f), 1f);\n\nfn main_1() {\n    var corner: vec2<f32>;\n    var indexable: array<vec2<f32>, 6>;\n    var p: vec2<f32>;\n    var ndc: vec2<f32>;\n    var orientation: f32;\n    var along: vec2<f32>;\n    var local: f32;\n\n    let _e31 = gl_VertexIndex_1;\n    indexable = array<vec2<f32>, 6>(vec2<f32>(0f, 0f), vec2<f32>(1f, 0f), vec2<f32>(0f, 1f), vec2<f32>(0f, 1f), vec2<f32>(1f, 0f), vec2<f32>(1f, 1f));\n    let _e33 = indexable[_e31];\n    corner = _e33;\n    let _e34 = aOrigin_1;\n    let _e35 = aEdges_1;\n    let _e38 = corner[0u];\n    let _e41 = aEdges_1;\n    let _e44 = corner[1u];\n    p = ((_e34 + (_e35.xy * _e38)) + (_e41.zw * _e44));\n    let _e49 = unnamed.uToNdc0_[0u];\n    let _e51 = p[0u];\n    let _e55 = unnamed.uToNdc0_[2u];\n    let _e57 = p[1u];\n    let _e62 = unnamed.uToNdc1_[0u];\n    let _e66 = unnamed.uToNdc0_[1u];\n    let _e68 = p[0u];\n    let _e72 = unnamed.uToNdc0_[3u];\n    let _e74 = p[1u];\n    let _e79 = unnamed.uToNdc1_[1u];\n    ndc = vec2<f32>((((_e49 * _e51) + (_e55 * _e57)) + _e62), (((_e66 * _e68) + (_e72 * _e74)) + _e79));\n    let _e84 = unnamed.uToNdc0_[0u];\n    let _e87 = unnamed.uToNdc0_[3u];\n    let _e91 = unnamed.uToNdc0_[1u];\n    let _e94 = unnamed.uToNdc0_[2u];\n    orientation = ((_e84 * _e87) - (_e91 * _e94));\n    let _e98 = corner[0u];\n    let _e99 = orientation;\n    if (_e99 > 0f) {\n        let _e102 = corner[1u];\n        local = (1f - _e102);\n    } else {\n        let _e105 = corner[1u];\n        local = _e105;\n    }\n    let _e106 = local;\n    along = vec2<f32>(_e98, _e106);\n    let _e108 = aUv_1;\n    let _e110 = aUv_1;\n    let _e112 = along;\n    vUv = mix(_e108.xy, _e110.zw, _e112);\n    let _e114 = aTint_1;\n    vTint = _e114;\n    let _e116 = unnamed.uClipCorrection;\n    let _e117 = ndc;\n    unnamed_1.gl_Position = (_e116 * vec4<f32>(_e117.x, _e117.y, 0f, 1f));\n    return;\n}\n\n@vertex \nfn main(@builtin(vertex_index) gl_VertexIndex: u32, @location(3) aOrigin: vec2<f32>, @location(0) aEdges: vec4<f32>, @location(1) aUv: vec4<f32>, @location(2) aTint: vec4<f32>) -> VertexOutput {\n    gl_VertexIndex_1 = i32(gl_VertexIndex);\n    aOrigin_1 = aOrigin;\n    aEdges_1 = aEdges;\n    aUv_1 = aUv;\n    aTint_1 = aTint;\n    main_1();\n    let _e16 = unnamed_1.gl_Position.y;\n    unnamed_1.gl_Position.y = -(_e16);\n    let _e18 = vUv;\n    let _e19 = vTint;\n    let _e20 = unnamed_1.gl_Position;\n    return VertexOutput(_e18, _e19, _e20);\n}\n";
 /**
  * What the transform assigned, so the renderer binds the same numbers.
  *

package/dist/shaders/sprite.d.ts

@@ -1,3 +1,3 @@
 /** The sprite program: one textured, tinted quad per instance, blended in submission order. */
-export declare const SPRITE_VERT = "#version 300 es\n\n/**\n * The two edge vectors of the quad, in the space the affine below maps from.\n *\n * Edge vectors rather than a size and an angle: the rotation is resolved on the CPU once per\n * sprite, where it costs one sine, and the vertex stage does two multiplies and an add. A sprite\n * batch is vertex-bound at four thousand quads and this is the whole of its vertex work.\n */\nlayout(location = 0) in vec4 aEdges;\n/** The frame this sprite reads, as (u0, v0) and (u1, v1). */\nlayout(location = 1) in vec4 aUv;\n/** Straight, not premultiplied. The fragment stage premultiplies after the texture fetch. */\nlayout(location = 2) in vec4 aTint;\n/** The corner the two edges grow from. */\nlayout(location = 3) in vec2 aOrigin;\n\n/**\n * The affine to normalised device coordinates, as (a, b, c, d) and (e, f).\n *\n * Two `vec4`s rather than a `mat3`, because a `mat3` in a uniform block is three\n * sixteen-byte rows for nine useful floats and this is read once per vertex.\n */\nuniform vec4 uToNdc0;\nuniform vec4 uToNdc1;\n/**\n * Clip space, as the backend drawing this defines it. Identity on WebGL2.\n *\n * The same correction `panel.ts` carries and for the same reason: this stage builds its own clip\n * position and never multiplies by a camera, so the generated vertex shader's Y negation would\n * stand uncancelled and the whole 2D layer would land mirrored about the middle of the frame.\n */\nuniform mat4 uClipCorrection;\n\nout vec2 vUv;\nout vec4 vTint;\n\n/**\n * Two triangles, wound so that either winding draws: this pass culls nothing.\n *\n * A sprite is flipped by giving it a negative width, which reverses the winding \u2014 so a cull mode\n * would silently drop every mirrored sprite, which is what a character facing left is.\n */\nconst vec2 CORNERS[6] = vec2[6](\n  vec2(0.0, 0.0), vec2(1.0, 0.0), vec2(0.0, 1.0),\n  vec2(0.0, 1.0), vec2(1.0, 0.0), vec2(1.0, 1.0)\n);\n\nvoid main() {\n  vec2 corner = CORNERS[gl_VertexID];\n  vec2 p = aOrigin + aEdges.xy * corner.x + aEdges.zw * corner.y;\n  vec2 ndc = vec2(\n    uToNdc0.x * p.x + uToNdc0.z * p.y + uToNdc1.x,\n    uToNdc0.y * p.x + uToNdc0.w * p.y + uToNdc1.y\n  );\n  vUv = mix(aUv.xy, aUv.zw, corner);\n  vTint = aTint;\n  /* z is 0 and nothing depth-tests here: the order sprites were submitted in is the layering. */\n  gl_Position = uClipCorrection * vec4(ndc, 0.0, 1.0);\n}\n";
+export declare const SPRITE_VERT = "#version 300 es\n\n/**\n * The two edge vectors of the quad, in the space the affine below maps from.\n *\n * Edge vectors rather than a size and an angle: the rotation is resolved on the CPU once per\n * sprite, where it costs one sine, and the vertex stage does two multiplies and an add. A sprite\n * batch is vertex-bound at four thousand quads and this is the whole of its vertex work.\n */\nlayout(location = 0) in vec4 aEdges;\n/** The frame this sprite reads, as (u0, v0) and (u1, v1). */\nlayout(location = 1) in vec4 aUv;\n/** Straight, not premultiplied. The fragment stage premultiplies after the texture fetch. */\nlayout(location = 2) in vec4 aTint;\n/** The corner the two edges grow from. */\nlayout(location = 3) in vec2 aOrigin;\n\n/**\n * The affine to normalised device coordinates, as (a, b, c, d) and (e, f).\n *\n * Two `vec4`s rather than a `mat3`, because a `mat3` in a uniform block is three\n * sixteen-byte rows for nine useful floats and this is read once per vertex.\n */\nuniform vec4 uToNdc0;\nuniform vec4 uToNdc1;\n/**\n * Clip space, as the backend drawing this defines it. Identity on WebGL2.\n *\n * The same correction `panel.ts` carries and for the same reason: this stage builds its own clip\n * position and never multiplies by a camera, so the generated vertex shader's Y negation would\n * stand uncancelled and the whole 2D layer would land mirrored about the middle of the frame.\n */\nuniform mat4 uClipCorrection;\n\nout vec2 vUv;\nout vec4 vTint;\n\n/**\n * Two triangles, wound so that either winding draws: this pass culls nothing.\n *\n * A sprite is flipped by giving it a negative width, which reverses the winding \u2014 so a cull mode\n * would silently drop every mirrored sprite, which is what a character facing left is.\n */\nconst vec2 CORNERS[6] = vec2[6](\n  vec2(0.0, 0.0), vec2(1.0, 0.0), vec2(0.0, 1.0),\n  vec2(0.0, 1.0), vec2(1.0, 0.0), vec2(1.0, 1.0)\n);\n\nvoid main() {\n  vec2 corner = CORNERS[gl_VertexID];\n  vec2 p = aOrigin + aEdges.xy * corner.x + aEdges.zw * corner.y;\n  vec2 ndc = vec2(\n    uToNdc0.x * p.x + uToNdc0.z * p.y + uToNdc1.x,\n    uToNdc0.y * p.x + uToNdc0.w * p.y + uToNdc1.y\n  );\n  /*\n   * **A picture keeps its top up in either space.** A frame's v runs down the image, and a sprite's\n   * second edge runs toward larger y: down the screen in screen space, up the world in a 2D world.\n   * So where the affine keeps orientation, which a world camera's does and the screen's does not,\n   * the frame's rows are read from the other end. Read from the affine rather than passed in,\n   * because a flag beside it could disagree with it. It was missing until 2026-10-02, and every\n   * sprite and tile drawn in a world came out upside down while every check, in screen space,\n   * passed.\n   */\n  float orientation = uToNdc0.x * uToNdc0.w - uToNdc0.y * uToNdc0.z;\n  vec2 along = vec2(corner.x, orientation > 0.0 ? 1.0 - corner.y : corner.y);\n  vUv = mix(aUv.xy, aUv.zw, along);\n  vTint = aTint;\n  /* z is 0 and nothing depth-tests here: the order sprites were submitted in is the layering. */\n  gl_Position = uClipCorrection * vec4(ndc, 0.0, 1.0);\n}\n";
 export declare const SPRITE_FRAG: string;

package/dist/shaders/sprite.js

@@ -65,7 +65,18 @@ void main() {
     uToNdc0.x * p.x + uToNdc0.z * p.y + uToNdc1.x,
     uToNdc0.y * p.x + uToNdc0.w * p.y + uToNdc1.y
   );
-  vUv = mix(aUv.xy, aUv.zw, corner);
+  /*
+   * **A picture keeps its top up in either space.** A frame's v runs down the image, and a sprite's
+   * second edge runs toward larger y: down the screen in screen space, up the world in a 2D world.
+   * So where the affine keeps orientation, which a world camera's does and the screen's does not,
+   * the frame's rows are read from the other end. Read from the affine rather than passed in,
+   * because a flag beside it could disagree with it. It was missing until 2026-10-02, and every
+   * sprite and tile drawn in a world came out upside down while every check, in screen space,
+   * passed.
+   */
+  float orientation = uToNdc0.x * uToNdc0.w - uToNdc0.y * uToNdc0.z;
+  vec2 along = vec2(corner.x, orientation > 0.0 ? 1.0 - corner.y : corner.y);
+  vUv = mix(aUv.xy, aUv.zw, along);
   vTint = aTint;
   /* z is 0 and nothing depth-tests here: the order sprites were submitted in is the layering. */
   gl_Position = uClipCorrection * vec4(ndc, 0.0, 1.0);

package/dist/uiDraw.d.ts

@@ -1,6 +1,6 @@
 /** Turn a laid-out interface tree into quads, parents first so children land on top. */
 import type { SpriteBatch } from './spriteBatch.ts';
-import type { UiNode } from './uiNode.ts';
+import type { UiNode, UiRect } from './uiNode.ts';
 /**
  * Where a caller draws what a quad cannot be.
  *
@@ -13,7 +13,12 @@ import type { UiNode } from './uiNode.ts';
  * label lands over its own background and under whatever is drawn after it.
  */
 export interface UiContentSink {
-    content(node: UiNode): void;
+    /**
+     * `visible` is the part of the node its clipping ancestors leave on screen, which outside any clip
+     * is the whole of it. Text has to be cut where the quads are, and only the caller drawing it can
+     * cut it: a label in a row half scrolled out of a list is skipped, or drawn cut, here.
+     */
+    content(node: UiNode, visible: UiRect): void;
 }
 /**
  * Draw a tree. Returns how many quads it came to.
@@ -22,6 +27,14 @@ export interface UiContentSink {
  * there is no depth here, so what is drawn later is what is on top. A node draws its background
  * first and its image second, so an icon lands on its own plate.
  *
+ * **A clipping node bounds what its descendants draw.** Each quad is cut to the rectangle every
+ * clipping ancestor leaves, on the CPU, and an image's frame is cut in proportion, so a scrolled list
+ * shows the rows inside it and nothing past its edges. Cut rather than scissored, because a scissor
+ * is state a contributed pass would have to set and restore on both backends, and a cut is four
+ * numbers per quad in the batch it already writes. Until 2026-10-02 `clip` was laid out, scrolled
+ * and documented, and drawn by nothing: a list's rows drew wherever they had scrolled to. The tree is
+ * in screen space, CSS pixels from the top-left, which is the space the cut assumes.
+ *
  * Allocates nothing. `layoutUiTree` must have run over this root, or every rect is whatever it was
  * left at.
  */

package/dist/uiDraw.js

@@ -1,12 +1,16 @@
 /** Turn a laid-out interface tree into quads, parents first so children land on top. */
 import { drawSprite } from './spriteBatch.js';
-/* One placement, refilled per node. This is a per-frame path and it is the only object in it. */
+import { createSpriteFrame } from './spriteSheet.js';
+/* One placement, refilled per node. This is a per-frame path and these are the only objects in it. */
 const PLACEMENT = {
     x: 0,
     y: 0,
     w: 0,
     h: 0,
 };
+/* The visible part of a node, handed to the sink, and the part of its frame that part shows. */
+const VISIBLE = { x: 0, y: 0, w: 0, h: 0 };
+const CUT = createSpriteFrame();
 /**
  * Draw a tree. Returns how many quads it came to.
  *
@@ -14,28 +18,82 @@ const PLACEMENT = {
  * there is no depth here, so what is drawn later is what is on top. A node draws its background
  * first and its image second, so an icon lands on its own plate.
  *
+ * **A clipping node bounds what its descendants draw.** Each quad is cut to the rectangle every
+ * clipping ancestor leaves, on the CPU, and an image's frame is cut in proportion, so a scrolled list
+ * shows the rows inside it and nothing past its edges. Cut rather than scissored, because a scissor
+ * is state a contributed pass would have to set and restore on both backends, and a cut is four
+ * numbers per quad in the batch it already writes. Until 2026-10-02 `clip` was laid out, scrolled
+ * and documented, and drawn by nothing: a list's rows drew wherever they had scrolled to. The tree is
+ * in screen space, CSS pixels from the top-left, which is the space the cut assumes.
+ *
  * Allocates nothing. `layoutUiTree` must have run over this root, or every rect is whatever it was
  * left at.
  */
 export function drawUiTree(batch, root, white, sink) {
-    if (root.hidden)
+    return drawWithin(batch, root, white, sink, -Infinity, -Infinity, Infinity, Infinity);
+}
+function drawWithin(batch, node, white, sink, left, top, right, bottom) {
+    if (node.hidden)
         return 0;
+    const rect = node.rect;
+    const clipped = left !== -Infinity;
+    const x0 = Math.max(rect.x, left);
+    const y0 = Math.max(rect.y, top);
+    const x1 = Math.min(rect.x + rect.w, right);
+    const y1 = Math.min(rect.y + rect.h, bottom);
     let drawn = 0;
-    PLACEMENT.x = root.rect.x;
-    PLACEMENT.y = root.rect.y;
-    PLACEMENT.w = root.rect.w;
-    PLACEMENT.h = root.rect.h;
-    if (root.background !== null) {
-        drawSprite(batch, white, PLACEMENT, null, root.background);
-        drawn += 1;
-    }
-    if (root.texture >= 0) {
-        drawSprite(batch, root.texture, PLACEMENT, root.frame, root.tint);
-        drawn += 1;
+    /*
+     * Inside a clip, a node cut away entirely draws nothing of its own. Outside one, nothing is cut and
+     * a node is drawn as it always was, whatever its size. Its children are cut one by one either way,
+     * since a child can lie outside its parent's box and still inside the clip.
+     */
+    if (!clipped || (x1 > x0 && y1 > y0)) {
+        PLACEMENT.x = clipped ? x0 : rect.x;
+        PLACEMENT.y = clipped ? y0 : rect.y;
+        PLACEMENT.w = clipped ? x1 - x0 : rect.w;
+        PLACEMENT.h = clipped ? y1 - y0 : rect.h;
+        if (node.background !== null) {
+            drawSprite(batch, white, PLACEMENT, null, node.background);
+            drawn += 1;
+        }
+        if (node.texture >= 0) {
+            const frame = clipped ? cutFrame(node, x0, y0, x1, y1) : node.frame;
+            drawSprite(batch, node.texture, PLACEMENT, frame, node.tint);
+            drawn += 1;
+        }
+        if (sink !== null && node.text !== '') {
+            VISIBLE.x = PLACEMENT.x;
+            VISIBLE.y = PLACEMENT.y;
+            VISIBLE.w = PLACEMENT.w;
+            VISIBLE.h = PLACEMENT.h;
+            sink.content(node, VISIBLE);
+        }
     }
-    if (sink !== null && root.text !== '')
-        sink.content(root);
-    for (const child of root.children)
-        drawn += drawUiTree(batch, child, white, sink);
+    /* What a clipping node leaves its children: its own box, inside whatever it was left itself. */
+    const keep = node.clip;
+    const cl = keep ? Math.max(left, rect.x) : left;
+    const ct = keep ? Math.max(top, rect.y) : top;
+    const cr = keep ? Math.min(right, rect.x + rect.w) : right;
+    const cb = keep ? Math.min(bottom, rect.y + rect.h) : bottom;
+    for (const child of node.children)
+        drawn += drawWithin(batch, child, white, sink, cl, ct, cr, cb);
     return drawn;
 }
+/** The part of a node's frame its visible box shows, or the whole frame when nothing was cut. */
+function cutFrame(node, x0, y0, x1, y1) {
+    const rect = node.rect;
+    if (x0 === rect.x && y0 === rect.y && x1 === rect.x + rect.w && y1 === rect.y + rect.h) {
+        return node.frame;
+    }
+    const u0 = node.frame?.u0 ?? 0;
+    const v0 = node.frame?.v0 ?? 0;
+    const u1 = node.frame?.u1 ?? 1;
+    const v1 = node.frame?.v1 ?? 1;
+    const perX = rect.w > 0 ? (u1 - u0) / rect.w : 0;
+    const perY = rect.h > 0 ? (v1 - v0) / rect.h : 0;
+    CUT.u0 = u0 + (x0 - rect.x) * perX;
+    CUT.u1 = u0 + (x1 - rect.x) * perX;
+    CUT.v0 = v0 + (y0 - rect.y) * perY;
+    CUT.v1 = v0 + (y1 - rect.y) * perY;
+    return CUT;
+}

package/dist/uiFocus.js

@@ -16,6 +16,10 @@ import { uiRectHolds } from './uiNode.js';
 export function uiHitTest(root, x, y) {
     if (root.hidden)
         return null;
+    /* A clipping node bounds its descendants here as it does in the picture: a row scrolled out of a
+       list is not under the pointer, whatever is drawn where it would have been. */
+    if (root.clip && !uiRectHolds(root, x, y))
+        return null;
     for (let i = root.children.length - 1; i >= 0; i -= 1) {
         const hit = uiHitTest(root.children[i], x, y);
         if (hit !== null)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/ui2d",
-  "version": "4.6.1",
+  "version": "4.7.1",
   "description": "The 2D layer: batched sprites, sheets, tilemaps, and a retained interface tree over them",
   "license": "Apache-2.0",
   "type": "module",
@@ -27,7 +27,7 @@
   ],
   "sideEffects": false,
   "peerDependencies": {
-    "@driftengine/core": "4.6.1"
+    "@driftengine/core": "4.7.1"
   },
   "author": "Drift Technologies",
   "repository": {

package/src/shaders/generated/sprite.wgsl.ts

@@ -7,7 +7,7 @@
 
 export const SPRITE_FRAG_WGSL = "struct Uniforms {\n    uOutputTransform: i32,\n    uOutputExposure: f32,\n}\n\n@group(0) @binding(1) \nvar<uniform> unnamed: Uniforms;\n@group(0) @binding(32) \nvar uSpriteTexture_t: texture_2d<f32>;\n@group(0) @binding(33) \nvar uSpriteTexture_s: sampler;\nvar<private> vUv_1: vec2<f32>;\nvar<private> vTint_1: vec4<f32>;\nvar<private> fragColor: vec4<f32>;\n\nfn linearToSrgb_u0028_vf3_u003b(c: ptr<function, vec3<f32>>) -> vec3<f32> {\n    var low: vec3<f32>;\n    var high: vec3<f32>;\n\n    let _e55 = (*c);\n    low = (_e55 * 12.92f);\n    let _e57 = (*c);\n    high = ((pow(max(_e57, vec3<f32>(0f, 0f, 0f)), vec3<f32>(0.41666666f, 0.41666666f, 0.41666666f)) * 1.055f) - vec3(0.055f));\n    let _e63 = high;\n    let _e64 = low;\n    let _e65 = (*c);\n    return mix(_e63, _e64, step(_e65, vec3<f32>(0.0031308f, 0.0031308f, 0.0031308f)));\n}\n\nfn rrtAndOdtFit_u0028_vf3_u003b(v: ptr<function, vec3<f32>>) -> vec3<f32> {\n    var a: vec3<f32>;\n    var b: vec3<f32>;\n\n    let _e55 = (*v);\n    let _e56 = (*v);\n    a = ((_e55 * (_e56 + vec3(0.0245786f))) - vec3(0.000090537f));\n    let _e62 = (*v);\n    let _e63 = (*v);\n    b = ((_e62 * ((_e63 * 0.983729f) + vec3(0.432951f))) + vec3(0.238081f));\n    let _e70 = a;\n    let _e71 = b;\n    return (_e70 / _e71);\n}\n\nfn acesFilmic_u0028_vf3_u003b(x: ptr<function, vec3<f32>>) -> vec3<f32> {\n    var param: vec3<f32>;\n\n    let _e55 = unnamed.uOutputExposure;\n    let _e56 = (*x);\n    (*x) = (_e56 * _e55);\n    let _e58 = (*x);\n    param = (mat3x3<f32>(vec3<f32>(0.59719f, 0.076f, 0.0284f), vec3<f32>(0.35458f, 0.90834f, 0.13383f), vec3<f32>(0.04823f, 0.01566f, 0.83777f)) * _e58);\n    let _e60 = rrtAndOdtFit_u0028_vf3_u003b((&param));\n    return clamp((mat3x3<f32>(vec3<f32>(1.60475f, -0.10208f, -0.00327f), vec3<f32>(-0.53108f, 1.10813f, -0.07276f), vec3<f32>(-0.07367f, -0.00605f, 1.07602f)) * _e60), vec3(0f), vec3(1f));\n}\n\nfn applyOutputTransform_u0028_vf3_u003b(c_1: ptr<function, vec3<f32>>) -> vec3<f32> {\n    var param_1: vec3<f32>;\n    var param_2: vec3<f32>;\n\n    let _e56 = unnamed.uOutputTransform;\n    if (_e56 == 0i) {\n        let _e58 = (*c_1);\n        return _e58;\n    }\n    let _e60 = unnamed.uOutputTransform;\n    if (_e60 == 2i) {\n        let _e62 = (*c_1);\n        param_1 = _e62;\n        let _e63 = acesFilmic_u0028_vf3_u003b((&param_1));\n        (*c_1) = _e63;\n    }\n    let _e64 = (*c_1);\n    param_2 = _e64;\n    let _e65 = linearToSrgb_u0028_vf3_u003b((&param_2));\n    return _e65;\n}\n\nfn main_1() {\n    var texel: vec4<f32>;\n    var colour: vec4<f32>;\n    var param_3: vec3<f32>;\n\n    let _e55 = vUv_1;\n    let _e56 = textureSample(uSpriteTexture_t, uSpriteTexture_s, _e55);\n    texel = _e56;\n    let _e57 = texel;\n    let _e58 = vTint_1;\n    colour = (_e57 * _e58);\n    let _e61 = colour[3u];\n    if (_e61 < 0.00392157f) {\n        discard;\n    }\n    let _e63 = colour;\n    param_3 = _e63.xyz;\n    let _e65 = applyOutputTransform_u0028_vf3_u003b((&param_3));\n    let _e66 = colour;\n    colour = vec4<f32>(_e65.x, _e65.y, _e65.z, _e66.w);\n    let _e72 = colour;\n    let _e75 = colour[3u];\n    let _e76 = (_e72.xyz * _e75);\n    let _e78 = colour[3u];\n    fragColor = vec4<f32>(_e76.x, _e76.y, _e76.z, _e78);\n    return;\n}\n\n@fragment \nfn main(@location(0) vUv: vec2<f32>, @location(1) vTint: vec4<f32>) -> @location(0) vec4<f32> {\n    vUv_1 = vUv;\n    vTint_1 = vTint;\n    main_1();\n    let _e5 = fragColor;\n    return _e5;\n}\n";
 
-export const SPRITE_VERT_WGSL = "struct Uniforms {\n    uToNdc0_: vec4<f32>,\n    uToNdc1_: vec4<f32>,\n    uClipCorrection: mat4x4<f32>,\n}\n\nstruct gl_PerVertex {\n    @builtin(position) gl_Position: vec4<f32>,\n    gl_PointSize: f32,\n}\n\nstruct VertexOutput {\n    @location(0) member: vec2<f32>,\n    @location(1) member_1: vec4<f32>,\n    @builtin(position) gl_Position: vec4<f32>,\n}\n\nvar<private> gl_VertexIndex_1: i32;\nvar<private> aOrigin_1: vec2<f32>;\nvar<private> aEdges_1: vec4<f32>;\n@group(0) @binding(0) \nvar<uniform> unnamed: Uniforms;\nvar<private> vUv: vec2<f32>;\nvar<private> aUv_1: vec4<f32>;\nvar<private> vTint: vec4<f32>;\nvar<private> aTint_1: vec4<f32>;\nvar<private> unnamed_1: gl_PerVertex = gl_PerVertex(vec4<f32>(0f, 0f, 0f, 1f), 1f);\n\nfn main_1() {\n    var corner: vec2<f32>;\n    var indexable: array<vec2<f32>, 6>;\n    var p: vec2<f32>;\n    var ndc: vec2<f32>;\n\n    let _e28 = gl_VertexIndex_1;\n    indexable = array<vec2<f32>, 6>(vec2<f32>(0f, 0f), vec2<f32>(1f, 0f), vec2<f32>(0f, 1f), vec2<f32>(0f, 1f), vec2<f32>(1f, 0f), vec2<f32>(1f, 1f));\n    let _e30 = indexable[_e28];\n    corner = _e30;\n    let _e31 = aOrigin_1;\n    let _e32 = aEdges_1;\n    let _e35 = corner[0u];\n    let _e38 = aEdges_1;\n    let _e41 = corner[1u];\n    p = ((_e31 + (_e32.xy * _e35)) + (_e38.zw * _e41));\n    let _e46 = unnamed.uToNdc0_[0u];\n    let _e48 = p[0u];\n    let _e52 = unnamed.uToNdc0_[2u];\n    let _e54 = p[1u];\n    let _e59 = unnamed.uToNdc1_[0u];\n    let _e63 = unnamed.uToNdc0_[1u];\n    let _e65 = p[0u];\n    let _e69 = unnamed.uToNdc0_[3u];\n    let _e71 = p[1u];\n    let _e76 = unnamed.uToNdc1_[1u];\n    ndc = vec2<f32>((((_e46 * _e48) + (_e52 * _e54)) + _e59), (((_e63 * _e65) + (_e69 * _e71)) + _e76));\n    let _e79 = aUv_1;\n    let _e81 = aUv_1;\n    let _e83 = corner;\n    vUv = mix(_e79.xy, _e81.zw, _e83);\n    let _e85 = aTint_1;\n    vTint = _e85;\n    let _e87 = unnamed.uClipCorrection;\n    let _e88 = ndc;\n    unnamed_1.gl_Position = (_e87 * vec4<f32>(_e88.x, _e88.y, 0f, 1f));\n    return;\n}\n\n@vertex \nfn main(@builtin(vertex_index) gl_VertexIndex: u32, @location(3) aOrigin: vec2<f32>, @location(0) aEdges: vec4<f32>, @location(1) aUv: vec4<f32>, @location(2) aTint: vec4<f32>) -> VertexOutput {\n    gl_VertexIndex_1 = i32(gl_VertexIndex);\n    aOrigin_1 = aOrigin;\n    aEdges_1 = aEdges;\n    aUv_1 = aUv;\n    aTint_1 = aTint;\n    main_1();\n    let _e16 = unnamed_1.gl_Position.y;\n    unnamed_1.gl_Position.y = -(_e16);\n    let _e18 = vUv;\n    let _e19 = vTint;\n    let _e20 = unnamed_1.gl_Position;\n    return VertexOutput(_e18, _e19, _e20);\n}\n";
+export const SPRITE_VERT_WGSL = "struct Uniforms {\n    uToNdc0_: vec4<f32>,\n    uToNdc1_: vec4<f32>,\n    uClipCorrection: mat4x4<f32>,\n}\n\nstruct gl_PerVertex {\n    @builtin(position) gl_Position: vec4<f32>,\n    gl_PointSize: f32,\n}\n\nstruct VertexOutput {\n    @location(0) member: vec2<f32>,\n    @location(1) member_1: vec4<f32>,\n    @builtin(position) gl_Position: vec4<f32>,\n}\n\nvar<private> gl_VertexIndex_1: i32;\nvar<private> aOrigin_1: vec2<f32>;\nvar<private> aEdges_1: vec4<f32>;\n@group(0) @binding(0) \nvar<uniform> unnamed: Uniforms;\nvar<private> vUv: vec2<f32>;\nvar<private> aUv_1: vec4<f32>;\nvar<private> vTint: vec4<f32>;\nvar<private> aTint_1: vec4<f32>;\nvar<private> unnamed_1: gl_PerVertex = gl_PerVertex(vec4<f32>(0f, 0f, 0f, 1f), 1f);\n\nfn main_1() {\n    var corner: vec2<f32>;\n    var indexable: array<vec2<f32>, 6>;\n    var p: vec2<f32>;\n    var ndc: vec2<f32>;\n    var orientation: f32;\n    var along: vec2<f32>;\n    var local: f32;\n\n    let _e31 = gl_VertexIndex_1;\n    indexable = array<vec2<f32>, 6>(vec2<f32>(0f, 0f), vec2<f32>(1f, 0f), vec2<f32>(0f, 1f), vec2<f32>(0f, 1f), vec2<f32>(1f, 0f), vec2<f32>(1f, 1f));\n    let _e33 = indexable[_e31];\n    corner = _e33;\n    let _e34 = aOrigin_1;\n    let _e35 = aEdges_1;\n    let _e38 = corner[0u];\n    let _e41 = aEdges_1;\n    let _e44 = corner[1u];\n    p = ((_e34 + (_e35.xy * _e38)) + (_e41.zw * _e44));\n    let _e49 = unnamed.uToNdc0_[0u];\n    let _e51 = p[0u];\n    let _e55 = unnamed.uToNdc0_[2u];\n    let _e57 = p[1u];\n    let _e62 = unnamed.uToNdc1_[0u];\n    let _e66 = unnamed.uToNdc0_[1u];\n    let _e68 = p[0u];\n    let _e72 = unnamed.uToNdc0_[3u];\n    let _e74 = p[1u];\n    let _e79 = unnamed.uToNdc1_[1u];\n    ndc = vec2<f32>((((_e49 * _e51) + (_e55 * _e57)) + _e62), (((_e66 * _e68) + (_e72 * _e74)) + _e79));\n    let _e84 = unnamed.uToNdc0_[0u];\n    let _e87 = unnamed.uToNdc0_[3u];\n    let _e91 = unnamed.uToNdc0_[1u];\n    let _e94 = unnamed.uToNdc0_[2u];\n    orientation = ((_e84 * _e87) - (_e91 * _e94));\n    let _e98 = corner[0u];\n    let _e99 = orientation;\n    if (_e99 > 0f) {\n        let _e102 = corner[1u];\n        local = (1f - _e102);\n    } else {\n        let _e105 = corner[1u];\n        local = _e105;\n    }\n    let _e106 = local;\n    along = vec2<f32>(_e98, _e106);\n    let _e108 = aUv_1;\n    let _e110 = aUv_1;\n    let _e112 = along;\n    vUv = mix(_e108.xy, _e110.zw, _e112);\n    let _e114 = aTint_1;\n    vTint = _e114;\n    let _e116 = unnamed.uClipCorrection;\n    let _e117 = ndc;\n    unnamed_1.gl_Position = (_e116 * vec4<f32>(_e117.x, _e117.y, 0f, 1f));\n    return;\n}\n\n@vertex \nfn main(@builtin(vertex_index) gl_VertexIndex: u32, @location(3) aOrigin: vec2<f32>, @location(0) aEdges: vec4<f32>, @location(1) aUv: vec4<f32>, @location(2) aTint: vec4<f32>) -> VertexOutput {\n    gl_VertexIndex_1 = i32(gl_VertexIndex);\n    aOrigin_1 = aOrigin;\n    aEdges_1 = aEdges;\n    aUv_1 = aUv;\n    aTint_1 = aTint;\n    main_1();\n    let _e16 = unnamed_1.gl_Position.y;\n    unnamed_1.gl_Position.y = -(_e16);\n    let _e18 = vUv;\n    let _e19 = vTint;\n    let _e20 = unnamed_1.gl_Position;\n    return VertexOutput(_e18, _e19, _e20);\n}\n";
 
 /**
  * What the transform assigned, so the renderer binds the same numbers.

package/src/shaders/sprite.ts

@@ -68,7 +68,18 @@ void main() {
     uToNdc0.x * p.x + uToNdc0.z * p.y + uToNdc1.x,
     uToNdc0.y * p.x + uToNdc0.w * p.y + uToNdc1.y
   );
-  vUv = mix(aUv.xy, aUv.zw, corner);
+  /*
+   * **A picture keeps its top up in either space.** A frame's v runs down the image, and a sprite's
+   * second edge runs toward larger y: down the screen in screen space, up the world in a 2D world.
+   * So where the affine keeps orientation, which a world camera's does and the screen's does not,
+   * the frame's rows are read from the other end. Read from the affine rather than passed in,
+   * because a flag beside it could disagree with it. It was missing until 2026-10-02, and every
+   * sprite and tile drawn in a world came out upside down while every check, in screen space,
+   * passed.
+   */
+  float orientation = uToNdc0.x * uToNdc0.w - uToNdc0.y * uToNdc0.z;
+  vec2 along = vec2(corner.x, orientation > 0.0 ? 1.0 - corner.y : corner.y);
+  vUv = mix(aUv.xy, aUv.zw, along);
   vTint = aTint;
   /* z is 0 and nothing depth-tests here: the order sprites were submitted in is the layering. */
   gl_Position = uClipCorrection * vec4(ndc, 0.0, 1.0);

package/src/uiDraw.ts

@@ -2,7 +2,9 @@
 
 import { drawSprite } from './spriteBatch.ts';
 import type { SpriteBatch, SpritePlacement } from './spriteBatch.ts';
-import type { UiNode } from './uiNode.ts';
+import { createSpriteFrame } from './spriteSheet.ts';
+import type { SpriteFrame } from './spriteSheet.ts';
+import type { UiNode, UiRect } from './uiNode.ts';
 
 /**
  * Where a caller draws what a quad cannot be.
@@ -16,16 +18,24 @@ import type { UiNode } from './uiNode.ts';
  * label lands over its own background and under whatever is drawn after it.
  */
 export interface UiContentSink {
-  content(node: UiNode): void;
+  /**
+   * `visible` is the part of the node its clipping ancestors leave on screen, which outside any clip
+   * is the whole of it. Text has to be cut where the quads are, and only the caller drawing it can
+   * cut it: a label in a row half scrolled out of a list is skipped, or drawn cut, here.
+   */
+  content(node: UiNode, visible: UiRect): void;
 }
 
-/* One placement, refilled per node. This is a per-frame path and it is the only object in it. */
+/* One placement, refilled per node. This is a per-frame path and these are the only objects in it. */
 const PLACEMENT: SpritePlacement & { x: number; y: number; w: number; h: number } = {
   x: 0,
   y: 0,
   w: 0,
   h: 0,
 };
+/* The visible part of a node, handed to the sink, and the part of its frame that part shows. */
+const VISIBLE: UiRect = { x: 0, y: 0, w: 0, h: 0 };
+const CUT = createSpriteFrame();
 
 /**
  * Draw a tree. Returns how many quads it came to.
@@ -34,6 +44,14 @@ const PLACEMENT: SpritePlacement & { x: number; y: number; w: number; h: number
  * there is no depth here, so what is drawn later is what is on top. A node draws its background
  * first and its image second, so an icon lands on its own plate.
  *
+ * **A clipping node bounds what its descendants draw.** Each quad is cut to the rectangle every
+ * clipping ancestor leaves, on the CPU, and an image's frame is cut in proportion, so a scrolled list
+ * shows the rows inside it and nothing past its edges. Cut rather than scissored, because a scissor
+ * is state a contributed pass would have to set and restore on both backends, and a cut is four
+ * numbers per quad in the batch it already writes. Until 2026-10-02 `clip` was laid out, scrolled
+ * and documented, and drawn by nothing: a list's rows drew wherever they had scrolled to. The tree is
+ * in screen space, CSS pixels from the top-left, which is the space the cut assumes.
+ *
  * Allocates nothing. `layoutUiTree` must have run over this root, or every rect is whatever it was
  * left at.
  */
@@ -43,21 +61,85 @@ export function drawUiTree(
   white: number,
   sink: UiContentSink | null,
 ): number {
-  if (root.hidden) return 0;
+  return drawWithin(batch, root, white, sink, -Infinity, -Infinity, Infinity, Infinity);
+}
+
+function drawWithin(
+  batch: SpriteBatch,
+  node: UiNode,
+  white: number,
+  sink: UiContentSink | null,
+  left: number,
+  top: number,
+  right: number,
+  bottom: number,
+): number {
+  if (node.hidden) return 0;
+  const rect = node.rect;
+  const clipped = left !== -Infinity;
+  const x0 = Math.max(rect.x, left);
+  const y0 = Math.max(rect.y, top);
+  const x1 = Math.min(rect.x + rect.w, right);
+  const y1 = Math.min(rect.y + rect.h, bottom);
   let drawn = 0;
-  PLACEMENT.x = root.rect.x;
-  PLACEMENT.y = root.rect.y;
-  PLACEMENT.w = root.rect.w;
-  PLACEMENT.h = root.rect.h;
-  if (root.background !== null) {
-    drawSprite(batch, white, PLACEMENT, null, root.background);
-    drawn += 1;
-  }
-  if (root.texture >= 0) {
-    drawSprite(batch, root.texture, PLACEMENT, root.frame, root.tint);
-    drawn += 1;
+  /*
+   * Inside a clip, a node cut away entirely draws nothing of its own. Outside one, nothing is cut and
+   * a node is drawn as it always was, whatever its size. Its children are cut one by one either way,
+   * since a child can lie outside its parent's box and still inside the clip.
+   */
+  if (!clipped || (x1 > x0 && y1 > y0)) {
+    PLACEMENT.x = clipped ? x0 : rect.x;
+    PLACEMENT.y = clipped ? y0 : rect.y;
+    PLACEMENT.w = clipped ? x1 - x0 : rect.w;
+    PLACEMENT.h = clipped ? y1 - y0 : rect.h;
+    if (node.background !== null) {
+      drawSprite(batch, white, PLACEMENT, null, node.background);
+      drawn += 1;
+    }
+    if (node.texture >= 0) {
+      const frame = clipped ? cutFrame(node, x0, y0, x1, y1) : node.frame;
+      drawSprite(batch, node.texture, PLACEMENT, frame, node.tint);
+      drawn += 1;
+    }
+    if (sink !== null && node.text !== '') {
+      VISIBLE.x = PLACEMENT.x;
+      VISIBLE.y = PLACEMENT.y;
+      VISIBLE.w = PLACEMENT.w;
+      VISIBLE.h = PLACEMENT.h;
+      sink.content(node, VISIBLE);
+    }
   }
-  if (sink !== null && root.text !== '') sink.content(root);
-  for (const child of root.children) drawn += drawUiTree(batch, child, white, sink);
+  /* What a clipping node leaves its children: its own box, inside whatever it was left itself. */
+  const keep = node.clip;
+  const cl = keep ? Math.max(left, rect.x) : left;
+  const ct = keep ? Math.max(top, rect.y) : top;
+  const cr = keep ? Math.min(right, rect.x + rect.w) : right;
+  const cb = keep ? Math.min(bottom, rect.y + rect.h) : bottom;
+  for (const child of node.children) drawn += drawWithin(batch, child, white, sink, cl, ct, cr, cb);
   return drawn;
 }
+
+/** The part of a node's frame its visible box shows, or the whole frame when nothing was cut. */
+function cutFrame(
+  node: UiNode,
+  x0: number,
+  y0: number,
+  x1: number,
+  y1: number,
+): SpriteFrame | null {
+  const rect = node.rect;
+  if (x0 === rect.x && y0 === rect.y && x1 === rect.x + rect.w && y1 === rect.y + rect.h) {
+    return node.frame;
+  }
+  const u0 = node.frame?.u0 ?? 0;
+  const v0 = node.frame?.v0 ?? 0;
+  const u1 = node.frame?.u1 ?? 1;
+  const v1 = node.frame?.v1 ?? 1;
+  const perX = rect.w > 0 ? (u1 - u0) / rect.w : 0;
+  const perY = rect.h > 0 ? (v1 - v0) / rect.h : 0;
+  CUT.u0 = u0 + (x0 - rect.x) * perX;
+  CUT.u1 = u0 + (x1 - rect.x) * perX;
+  CUT.v0 = v0 + (y0 - rect.y) * perY;
+  CUT.v1 = v0 + (y1 - rect.y) * perY;
+  return CUT;
+}

package/src/uiFocus.ts

@@ -18,6 +18,9 @@ import type { UiNode } from './uiNode.ts';
  */
 export function uiHitTest(root: UiNode, x: number, y: number): UiNode | null {
   if (root.hidden) return null;
+  /* A clipping node bounds its descendants here as it does in the picture: a row scrolled out of a
+     list is not under the pointer, whatever is drawn where it would have been. */
+  if (root.clip && !uiRectHolds(root, x, y)) return null;
   for (let i = root.children.length - 1; i >= 0; i -= 1) {
     const hit = uiHitTest(root.children[i] as UiNode, x, y);
     if (hit !== null) return hit;