Text: gradient fills, moving labels, and the typings the docs promised

[obiot]

Started as one Safari bug and turned into the thread it was hanging from.

The Text bakes

Gradient fills were clipped to the font box on Safari. WebKit rasterizes gradient-filled canvas text through a mask sized from the font's layout box rather than its ink, so glyphs rising above the declared ascent — routine for a display face — came out fully transparent under an intact stroke. Measured on a plain canvas with no engine involved: a flat fill paints 7px above the top alignment point on both engines, a gradient fill reaches 0 on WebKit. Gradient text is now filled flat and re-coloured through source-in, which runs every browser down the same rasterizer. Done unconditionally rather than behind a UA check.

A label that moved did not move. TextMetrics#x/y — the box the bake is blitted at — derives from pos, but nothing else in measureText does, so it refreshed only when the string changed. Reposition a label without re-setting its text and the bake offset grew by the whole distance travelled while the canvas stayed its original size: the glyphs slid off their own canvas and the blit went to where the label used to be. Split out as TextMetrics#updateOrigin, refreshed from the draw path.

The sub-pixel design is preserved rather than relocated: the canvas still floors onto a whole pixel (a fractional blit resamples the texture and goes soft) and the dropped fraction still lands in the bake where the rasterizer antialiases it. A new spec pins both halves — whole-pixel landing at fractional and negative positions, a whole-pixel move leaving the glyph phase bit-identical, a sub-pixel move moving the phase and not the canvas.

Ink padding was a pixel short. actualBoundingBox* describes the outline; antialiasing and pixel snapping paint past it. Measured a full pixel beyond on both engines, which was enough to shear the top row off a stroke.

The typings the docs promised

Type-checking an example against the shipped declarations found documented options the types denied. Mesh declared its 27 settings inline, so InstancedMesh — which forwards them wholesale and says so — rejected all of them; extracted as MeshSettings and intersected. setCurrentAnimation(name, { loop: true }), the form the class's own example uses, did not compile: the parameter was typed against the normalized options where loop and speed are mandatory. Stage#update and #draw were marked internal and stripped, so a custom stage could not call super.update(dt) in TypeScript while the skills and examples all teach exactly that.

Also Container#setChildsProperty's value, HTMLCanvasElement as image/texture, Text's bold/italic, Sprite3d's transparent/fog/castGroundShadow/shadowGroundY/shadowOpacity, and NoiseTexture2d's forwarded Noise settings.

One behaviour fix rides along: Sprite3d builds its own settings for Mesh and fog was not among the keys it copied, so fog: false — the only way to keep a sun out of the haze — silently did nothing.

Silent no-ops in the examples

Every one found by the type checker, every one code that reads correctly and does nothing:

• new Light3d(0, 0, {…}) — the constructor takes options alone, so JavaScript dropped the object and both lights ran on defaults. A type: "ambient" written this way is a second directional light. Two shipped examples.
• direction: new Vector3d(…) — an [x, y, z] array read by index, so a Vector3d yields NaN and the light contributes nothing. Fixing the arity is what exposed it; TypeScript stops checking a literal once the count is wrong.
• and then the sign: direction is where the light travels, and this is a Y-down space, so a sun overhead is +Y. Both examples lit their subjects from underneath — never visible while the options were being discarded. See Light3d: accept a Vector3d for direction and position, as color already accepts a Color #1661 for accepting a Vector3d here.
• blendMode in a settings literal — only the renderer reads that setting, never a renderable.

Audio

audio.tone() and audio.noise() take a delay in seconds, scheduled on the audio clock. Sequencing a stinger needed a setTimeout around the second call, which fires on the main thread and slips the note on a busy frame. Optional and defaulting to 0, so existing calls schedule exactly where they always did; the spec asserts that explicitly alongside the gap being the delay.

Also

ScoreFly in the plinko example was a Container wrapping one Text, because moving a Text did not move it — the wrapper held the label at its local origin and moved the container. It is a Text now. Its pos.set(x, y) was also wiping depth every frame, depth being pos.z.

The Camera3d (perspective) example is removed — three sprites stacked along z, written to prove per-sprite depth reached the vertex stream during the original Camera3d PRs.

Skills gained the Light3d traps and the Y-down sign, Camera3d#worldToScreen (which was in no skill at all), the settings-key and isRenderable no-ops, and a BitmapText section its own frontmatter had been advertising. The unreleased changelog section was trimmed from 594 characters an entry to 288; 18.3.0 is the reference at ~250.

Verification

Full suite 282 files / 6864 passed / 9 skipped. Typedoc 0 errors and 154 warnings, three below the starting point. Rendering verified on headless WebGL2, Chrome WebGPU and WebKit WebGPU throughout — the harness that does it is held back with the example that motivated it.

Both new specs were checked by removing the fix and confirming they go red.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.