@solidrt/2d 0.0.67 → 0.0.69

package/src/shaders.ts

@@ -1,46 +1,60 @@
-// The sprite pipelines: a unit quad instanced over one atlas, mapped
-// world -> clip through uCamera (offset + zoom), uCameraRot ([cos, sin,
-// pivotX, pivotY]: the camera rotation about the pivot, identity
+// The sprite pipelines: a unit quad instanced over a layer's atlases,
+// mapped world -> clip through uCamera (offset + zoom), uCameraRot ([cos,
+// sin, pivotX, pivotY]: the camera rotation about the pivot, identity
 // [1, 0, 0, 0]) and uViewport - the projectCamera mapping (camera.ts)
 // spelled in GLSL; the two must agree. World and clip space are both
 // y-down (core gpu.ts pixel contract), so the mapping carries NO flip
 // anywhere - do not add one. Two record layouts share the fragment stage:
-// - VERTEX + INSTANCE_ATTRIBUTES: the 13-float interleaved record
-//   [cx, cy, w, h, u0, v0, u1, v1, rot, tintR, tintG, tintB, tintA],
-//   used by the records layer (records.ts) and the tile layer (tiles.ts).
-// - VERTEX_SPLIT + INSTANCE_ATTRIBUTES_SPLIT: the node-backed live layer
+// - VERTEX + INSTANCE_ATTRIBUTES: the 20-float interleaved record
+//   [cx, cy, w, h, u0, v0, u1, v1, rot, tintR, tintG, tintB, tintA,
+//   minScreenPx, maxScreenPx, atlas, outlineR, outlineG, outlineB,
+//   outlineWidth], used by the records layer (records.ts) and the tile
+//   layer (tiles.ts).
+// - VERTEX_SPLIT + INSTANCE_LAYOUTS_SPLIT: the node-backed live layer
 //   (layer.ts), pose and style in separate instance-buffer slots - slot 0
 //   is the core-written Pose2D record [x, y, angle, sx, sy], slot 1 the
 //   JS-written style record [u0, v0, u1, v1, tintR, tintG, tintB, tintA,
-//   renderOrder]. The shader never reads iRenderOrder - it exists for the
-//   core's instanceOrder (orderBy: "renderOrder"); declared attributes without an
-//   active program attribute are skipped, their bytes pad the stride.
+//   renderOrder, minScreenPx, maxScreenPx, atlas, outlineR, outlineG,
+//   outlineB, outlineWidth]. The shader never reads iRenderOrder - it
+//   exists for the core's instanceOrder (orderBy: "renderOrder");
+//   declared attributes without an active program attribute are skipped,
+//   their bytes pad the stride.
+// `atlas` is the sampler index of the record's texture in the layer's
+// atlas list: the fragment stage is GENERATED per layer with one sampler
+// per declared atlas (fragmentFor), the flat per-instance index picking
+// the sampler - the multi-texture batch of PixiJS and Phaser, where Unity
+// and Godot break the batch on every texture change. Any number of sheets
+// interleave in one draw, key order included. An atlas declared as a
+// distance field (`Atlas.sdf`) is decoded in its branch instead of
+// sampled as colour: the median of rgb is the edge, anti-aliased over one
+// screen pixel from the quad's own texel footprint (the msdfgen reference
+// shader), the true field in alpha grows the per-instance outline.
+// `outline` is rgb plus a width in WORLD pixels; the vertex stage turns
+// the width into screen pixels through the camera zoom and the screen-size
+// clamp, so an outline scales with its glyph. A colour atlas ignores it.
+// Both vertex stages apply the screen-size clamp (SpriteOptions.
+// minScreenPx/maxScreenPx) through core's screenSizeScale: the quad
+// scales uniformly so its smaller axis stays within the bounds at the
+// camera's zoom (the pixels per world unit), and picking applies the JS
+// twin to the rect it tests.
 // The rotations here (clockwise, y-down) and their JS partners must
 // agree: iRot with pointInSprite in pick.ts, uCameraRot with
 // projectCamera in camera.ts. The differential checks guard the JS side
 // against oracles but NOT against these shaders - if you touch one
 // rotation, touch all.
-import { compileShader, createBuffer, createRenderPipeline, destroyBuffer, destroyProgram, destroyRenderPipeline, destroyShader, glsl, linkProgram } from "@solidrt/core/gpu"
-import type { BufferId, RenderPipelineId, VertexAttribute } from "@solidrt/core/gpu"
+import { compileShader, createBuffer, createRenderPipeline, destroyBuffer, destroyProgram, destroyRenderPipeline, destroyShader, glsl, linkProgram, SCREEN_SIZE_GLSL } from "@solidrt/core/gpu"
+import type { BlendMode, BufferId, RenderPipelineId, TextureBindings, TextureId, VertexAttribute } from "@solidrt/core/gpu"
 
-export let VERTEX = glsl`
-  in vec2 aPos;
-  in vec2 iCenter;
-  in vec2 iSize;
-  in vec4 iUv;
-  in float iRot;
-  in vec4 iTint;
-  out vec2 vUv;
-  flat out vec4 vFrame;
-  out vec4 vTint;
-  uniform vec2 uViewport;
-  uniform vec4 uCamera;
-  uniform vec4 uCameraRot;
+/** What the fragment stage reads of a declared atlas: whether it is a
+ * distance field, and its range (see `Atlas.sdf`). */
+export type AtlasShading = { sdf?: { range: number } }
 
-  void main() {
-    vec2 corner = aPos * iSize;
-    float c = cos(iRot), s = sin(iRot);
-    vec2 world = iCenter + vec2(corner.x * c - corner.y * s, corner.x * s + corner.y * c);
+// The world -> clip mapping and the varyings both vertex stages share;
+// `corner` is the quad corner after the screen-size clamp, `center` the
+// sprite's world position.
+const VERTEX_BODY = glsl`
+    float c = cos(rot), s = sin(rot);
+    vec2 world = center + vec2(corner.x * c - corner.y * s, corner.x * s + corner.y * c);
     vec2 view = (world - uCamera.xy) * uCamera.zw;
     vec2 screen = uCameraRot.zw + vec2(view.x * uCameraRot.x - view.y * uCameraRot.y, view.x * uCameraRot.y + view.y * uCameraRot.x);
     // World and clip are both y-down, so the mapping carries no flip.
@@ -48,47 +62,182 @@ export let VERTEX = glsl`
     vUv = mix(iUv.xy, iUv.zw, aPos + 0.5);
     vFrame = iUv;
     vTint = iTint;
+    vAtlas = int(iAtlas);
+    vOutlineColor = iOutline.rgb;
+    // World pixels to screen pixels: the camera zoom, and the clamp the
+    // quad itself scaled by.
+    vOutlinePx = iOutline.a * uCamera.z * clampScale;
+`
+
+const VARYINGS = glsl`
+  out vec2 vUv;
+  flat out vec4 vFrame;
+  out vec4 vTint;
+  flat out int vAtlas;
+  flat out vec3 vOutlineColor;
+  flat out float vOutlinePx;
+  uniform vec2 uViewport;
+  uniform vec4 uCamera;
+  uniform vec4 uCameraRot;
+`
+
+export let VERTEX = glsl`
+  in vec2 aPos;
+  in vec2 iCenter;
+  in vec2 iSize;
+  in vec4 iUv;
+  in float iRot;
+  in vec4 iTint;
+  in vec2 iScreenPx;
+  in float iAtlas;
+  in vec4 iOutline;
+  ${VARYINGS}
+  ${SCREEN_SIZE_GLSL}
+  void main() {
+    float clampScale = screenSizeScale(iSize, uCamera.z, iScreenPx);
+    vec2 corner = aPos * iSize * clampScale;
+    vec2 center = iCenter;
+    float rot = iRot;
+    ${VERTEX_BODY}
   }
 `
 
-// uTint is the LAYER tint, multiplied over the per-instance vTint (identity
-// [1, 1, 1, 1] - GLSL uniforms default to ZERO, so every pipeline creation
-// must pin it explicitly or everything renders transparent black).
-//
-// The sample is clamped to its frame, pulled in by half a texel: a quad at
-// a fractional position lands edge samples so close to the frame's edge
-// that a linear tap (and float interpolation under nearest) reaches the
-// cell next door, painting a one-texel line of the neighbour along the
-// sprite's edge. The clamp keeps the quad's texel mapping 1:1 and only
-// moves those edge samples onto the edge texel, so touching cells do not
-// bleed and no gutter or inset is needed at mip level 0. It cannot help a
-// mip chain, whose texels straddle the cell edge before sampling - that is
-// okf/backlog/2d-atlas-extrude.md. min/max because a flipped frame stores
-// its UVs swapped, and the inner min/max because a sub-texel frame would
-// otherwise hand clamp() a lower bound above its upper one.
-export let FRAGMENT = glsl`
+/** The sampler uniform of atlas `i` in a layer's pipeline. */
+export function atlasUniform(i: number): string {
+  return `uAtlas${i}`
+}
+
+/** The texture bindings of a layer's atlases, by sampler uniform: what
+ * every target drawing with the layer's pipeline binds. */
+export function atlasBindings(atlases: readonly TextureId[]): TextureBindings {
+  let out: TextureBindings = {}
+  atlases.forEach((texture, i) => (out[atlasUniform(i)] = texture))
+  return out
+}
+
+/**
+ * The fragment stage of a layer over its atlases: one sampler per atlas,
+ * the record's atlas index (flat, so one per instance) picking it, and a
+ * distance-field decode in the branch of every atlas declared `sdf`.
+ *
+ * uTint is the LAYER tint, multiplied over the per-instance vTint
+ * (identity [1, 1, 1, 1] - GLSL uniforms default to ZERO, so every target
+ * creation must pin it explicitly or everything renders transparent
+ * black).
+ *
+ * The sample is clamped to its frame, pulled in by half a texel of ITS
+ * atlas: a quad at a fractional position lands edge samples so close to
+ * the frame's edge that a linear tap (and float interpolation under
+ * nearest) reaches the cell next door, painting a one-texel line of the
+ * neighbour along the sprite's edge. The clamp keeps the quad's texel
+ * mapping 1:1 and only moves those edge samples onto the edge texel, so
+ * touching cells do not bleed and no gutter is needed at mip level 0. It
+ * cannot help a mip chain, whose texels straddle the cell edge before
+ * sampling - that is extrude.ts. min/max because a flipped frame stores
+ * its UVs swapped, and the inner min/max because a sub-texel frame would
+ * otherwise hand clamp() a lower bound above its upper one.
+ *
+ * The derivatives are taken from the UNCLAMPED uv before any branch and
+ * the tap is textureGrad: the mip footprint is the quad's own (a clamped
+ * uv has a zero derivative along the clamped axis, which would pick a
+ * sharper level along every edge), and the lookup is well defined inside
+ * the per-instance branch (an implicit-derivative texture() in
+ * non-uniform control flow is not, which the PixiJS-style batch lives
+ * with). A single-atlas layer skips the branch and keeps the same tap.
+ *
+ * A colour atlas yields the texel times the instance tint (premultiplied
+ * in, premultiplied out). A distance-field atlas yields the instance
+ * tint as the fill, anti-aliased over one screen pixel: the field's range
+ * mapped through the quad's texel footprint gives the screen pixels per
+ * field unit (floored at 1, so a glyph far below its texel size fades
+ * instead of vanishing), the median of rgb is the edge, and when the
+ * instance carries an outline the true field in alpha, pushed out by the
+ * outline's screen pixels, paints the outline colour under the fill.
+ */
+export function fragmentFor(atlases: readonly AtlasShading[]): string {
+  if (!Array.isArray(atlases) || atlases.length === 0) throw new Error(`fragmentFor: atlases must be a non-empty list, got ${JSON.stringify(atlases)}`)
+  let samplers = ""
+  atlases.forEach((_, i) => (samplers += `uniform sampler2D ${atlasUniform(i)};\n  `))
+  let shade = (i: number) => {
+    let sdf = atlases[i]!.sdf
+    if (sdf === undefined) return `tap(${atlasUniform(i)}, dx, dy) * vTint`
+    if (!(typeof sdf.range === "number" && sdf.range > 0 && Number.isFinite(sdf.range))) {
+      throw new Error(`fragmentFor: atlases[${i}].sdf.range must be a positive number, got ${sdf.range}`)
+    }
+    return `field(${atlasUniform(i)}, ${sdf.range.toFixed(2)}, dx, dy)`
+  }
+  let cases = ""
+  atlases.forEach((_, i) => (cases += `case ${i}: color = ${shade(i)}; break;\n      `))
+  let pick =
+    atlases.length === 1
+      ? `vec4 color = ${shade(0)};`
+      : `vec4 color;
+    switch (vAtlas) {
+      ${cases}default: color = ${shade(0)}; break;
+    }`
+  return glsl`
   in vec2 vUv;
   flat in vec4 vFrame;
   in vec4 vTint;
-  uniform sampler2D uAtlas;
-  uniform vec4 uTint;
+  flat in int vAtlas;
+  flat in vec3 vOutlineColor;
+  flat in float vOutlinePx;
+  ${samplers}uniform vec4 uTint;
 
-  void main() {
-    vec2 halfTexel = 0.5 / vec2(textureSize(uAtlas, 0));
+  vec4 tap(sampler2D atlas, vec2 dx, vec2 dy) {
+    vec2 halfTexel = 0.5 / vec2(textureSize(atlas, 0));
     vec2 lo = min(vFrame.xy, vFrame.zw) + halfTexel;
     vec2 hi = max(vFrame.xy, vFrame.zw) - halfTexel;
-    vec2 uv = clamp(vUv, min(lo, hi), max(lo, hi));
-    fragColor = texture(uAtlas, uv) * vTint * uTint;
+    return textureGrad(atlas, clamp(vUv, min(lo, hi), max(lo, hi)), dx, dy);
+  }
+
+  float median3(vec3 v) {
+    return max(min(v.r, v.g), min(max(v.r, v.g), v.b));
+  }
+
+  // Screen pixels per field unit (0..1 spans the range): the range in
+  // texels over the quad's texel footprint per screen pixel, floored at
+  // one so a minified glyph fades rather than aliasing away.
+  float screenPxRange(sampler2D atlas, float range, vec2 dx, vec2 dy) {
+    vec2 unitRange = vec2(range) / vec2(textureSize(atlas, 0));
+    vec2 screenTexSize = vec2(1.0) / (abs(dx) + abs(dy));
+    return max(0.5 * dot(unitRange, screenTexSize), 1.0);
+  }
+
+  vec4 field(sampler2D atlas, float range, vec2 dx, vec2 dy) {
+    vec4 t = tap(atlas, dx, dy);
+    float px = screenPxRange(atlas, range, dx, dy);
+    float fill = clamp((median3(t.rgb) - 0.5) * px + 0.5, 0.0, 1.0);
+    vec3 rgb = vTint.rgb;
+    float coverage = fill;
+    if (vOutlinePx > 0.0) {
+      float outline = clamp((t.a - 0.5) * px + vOutlinePx + 0.5, 0.0, 1.0);
+      coverage = max(fill, outline);
+      rgb = mix(vOutlineColor, vTint.rgb, fill);
+    }
+    float a = coverage * vTint.a;
+    return vec4(rgb * a, a);
+  }
+
+  void main() {
+    vec2 dx = dFdx(vUv);
+    vec2 dy = dFdy(vUv);
+    ${pick}
+    fragColor = color * uTint;
   }
 `
+}
 
-/** The instance attribute list matching the 13-float record layout. */
+/** The instance attribute list matching the 20-float record layout. */
 export const INSTANCE_ATTRIBUTES: VertexAttribute[] = [
   { name: "iCenter", format: "float32x2" },
   { name: "iSize", format: "float32x2" },
   { name: "iUv", format: "float32x4" },
   { name: "iRot", format: "float32" },
   { name: "iTint", format: "float32x4" },
+  { name: "iScreenPx", format: "float32x2" },
+  { name: "iAtlas", format: "float32" },
+  { name: "iOutline", format: "float32x4" },
 ]
 
 export let VERTEX_SPLIT = glsl`
@@ -98,24 +247,17 @@ export let VERTEX_SPLIT = glsl`
   in vec2 iScale;
   in vec4 iUv;
   in vec4 iTint;
-  out vec2 vUv;
-  flat out vec4 vFrame;
-  out vec4 vTint;
-  uniform vec2 uViewport;
-  uniform vec4 uCamera;
-  uniform vec4 uCameraRot;
-
+  in vec2 iScreenPx;
+  in float iAtlas;
+  in vec4 iOutline;
+  ${VARYINGS}
+  ${SCREEN_SIZE_GLSL}
   void main() {
-    vec2 corner = aPos * iScale;
-    float c = cos(iRot), s = sin(iRot);
-    vec2 world = iPos + vec2(corner.x * c - corner.y * s, corner.x * s + corner.y * c);
-    vec2 view = (world - uCamera.xy) * uCamera.zw;
-    vec2 screen = uCameraRot.zw + vec2(view.x * uCameraRot.x - view.y * uCameraRot.y, view.x * uCameraRot.y + view.y * uCameraRot.x);
-    // World and clip are both y-down, so the mapping carries no flip.
-    gl_Position = vec4(screen / uViewport * 2.0 - 1.0, 0.0, 1.0);
-    vUv = mix(iUv.xy, iUv.zw, aPos + 0.5);
-    vFrame = iUv;
-    vTint = iTint;
+    float clampScale = screenSizeScale(iScale, uCamera.z, iScreenPx);
+    vec2 corner = aPos * iScale * clampScale;
+    vec2 center = iPos;
+    float rot = iRot;
+    ${VERTEX_BODY}
   }
 `
 
@@ -132,6 +274,9 @@ export const INSTANCE_LAYOUTS_SPLIT: VertexAttribute[][] = [
     { name: "iUv", format: "float32x4" },
     { name: "iTint", format: "float32x4" },
     { name: "iRenderOrder", format: "float32" },
+    { name: "iScreenPx", format: "float32x2" },
+    { name: "iAtlas", format: "float32" },
+    { name: "iOutline", format: "float32x4" },
   ],
 ]
 
@@ -141,20 +286,22 @@ export type SpritePipeline = { quad: BufferId; pipeline: RenderPipelineId; dispo
 
 /**
  * Compile one sprite pipeline: `vertex` with its matching attribute list
- * (VERTEX + INSTANCE_ATTRIBUTES, or the split pair) over the shared
- * fragment stage, alpha-blended triangle strips. Spelled out (not the
- * fused createPipelineTexture) so a layer's targets - its own and every
- * view - add entries over the one pipeline. The program lives as long as
- * the pipeline; `dispose` frees both and the quad.
+ * (VERTEX + INSTANCE_ATTRIBUTES, or the split pair) over the fragment
+ * stage generated for `atlases` (count and distance-field decodes),
+ * triangle strips blended with `blend` (the layer's `blend` option,
+ * "alpha" by default). Spelled out (not the fused createPipelineTexture)
+ * so a layer's targets - its views, a tile layer's chunks - share the one
+ * compile. The program lives as long as the pipeline; `dispose` frees
+ * both and the quad.
  */
-export function createSpritePipeline(label: string, vertex: string, instanceLayouts: VertexAttribute[][]): SpritePipeline {
+export function createSpritePipeline(label: string, vertex: string, instanceLayouts: VertexAttribute[][], blend: BlendMode, atlases: readonly AtlasShading[]): SpritePipeline {
   // One unit quad (triangle strip), reused by every instance.
   let quad = createBuffer(new Float32Array([-0.5, -0.5, 0.5, -0.5, -0.5, 0.5, 0.5, 0.5]), {
     label: `${label}-quad`,
     autoFree: false,
   })
   let vs = compileShader("vertex", vertex, { header: true })
-  let fs = compileShader("fragment", FRAGMENT, { header: true })
+  let fs = compileShader("fragment", fragmentFor(atlases), { header: true })
   let program = linkProgram(vs, fs, { label })
   destroyShader(vs)
   destroyShader(fs)
@@ -162,7 +309,7 @@ export function createSpritePipeline(label: string, vertex: string, instanceLayo
     label,
     topology: "triangle-strip",
     buffers: [{ attributes: [{ name: "aPos", format: "float32x2" }] }, ...instanceLayouts.map(attributes => ({ stepMode: "instance" as const, attributes }))],
-    blend: "alpha",
+    blend,
   })
   return {
     quad,

package/src/shots.ts

@@ -17,7 +17,7 @@ const INITIAL: CameraState = { x: 0, y: 0, zoom: 1, rotation: 0, pivotX: 0, pivo
 let lerp = (a: number, b: number, t: number) => a + (b - a) * t
 
 /** Interpolate two 2d cameras: everything linear, the zoom in log space. */
-export let mixCamera2d = (a: CameraState, b: CameraState, t: number): CameraState => ({
+export let mixCamera = (a: CameraState, b: CameraState, t: number): CameraState => ({
   x: lerp(a.x, b.x, t),
   y: lerp(a.y, b.y, t),
   zoom: a.zoom * Math.pow(b.zoom / a.zoom, t),
@@ -26,25 +26,39 @@ export let mixCamera2d = (a: CameraState, b: CameraState, t: number): CameraStat
   pivotY: lerp(a.pivotY, b.pivotY, t),
 })
 
-export type ShotsHandle = ShotBlend<CameraState>
+/** A shot's target: the recording half plus the first view's size, so a
+ * createCamera2d drives it exactly like the view. */
 export type ShotTarget = RecordingTarget<CameraState> & Camera2dTarget
 
+export type ShotsHandle = Omit<ShotBlend<CameraState>, "shot"> & { shot(name: string, opts?: { priority?: number }): ShotTarget }
+
 /**
  * Shots over a view (or several: one output over a scene's layers):
- * `shot(name, { priority? })` returns the target a `createCamera2d` (or
- * a `<Camera2d>` through a custom viewport) drives; `activate(name, {
- * blend? })` makes it live when its priority wins, blending from the
- * current output; `update(dt)` from a frame loop while `active()`.
+ * `shot(name, { priority? })` returns the target a `createCamera2d`
+ * drives (its `camera()` is the shot's own, its `size()` the first
+ * view's); `activate(name, { blend? })` makes it live when its priority
+ * wins, blending from the current output; `update(dt)` from a frame
+ * loop while `active()`.
  */
 export function createShots(target: Camera2dTarget | Camera2dTarget[], options: ShotBlendOptions = {}): ShotsHandle {
   let targets = Array.isArray(target) ? target : [target]
-  for (let t of targets) if (!t || typeof t.setCamera !== "function") throw new Error("createShots: every target needs setCamera() (a view)")
-  return createShotBlend<CameraState>(
+  for (let t of targets) {
+    if (!t || typeof t.setCamera !== "function" || typeof t.size !== "function") throw new Error("createShots: every target needs setCamera() and size() (a view)")
+  }
+  let first = targets[0]!
+  let blend = createShotBlend<CameraState>(
     camera => {
       for (let t of targets) t.setCamera(camera)
     },
-    mixCamera2d,
+    mixCamera,
     INITIAL,
     options,
   )
+  return {
+    ...blend,
+    shot(name, opts) {
+      let rec = blend.shot(name, opts)
+      return { setCamera: rec.setCamera, camera: rec.camera, size: () => first.size() }
+    },
+  }
 }

package/src/text-layout.ts

@@ -0,0 +1,163 @@
+// Text layout, pure: the units of a text prepared on the glyph engine
+// (every unit carrying its glyphs) to one placement per glyph, in run
+// pixels from the run's anchor point, plus the lines and the run's box.
+// The line breaking is core's `layoutNextLine` (greedy over wrap units,
+// glued pieces kept together, a hard break ending a line, an overlong
+// unit placed whole), restated here rather than imported because core
+// loads the gui modules and this file is checked headless on the flux
+// binary (tests/text-layout.test.ts), like frames.ts. No GPU or GUI
+// imports: the PreparedText import is a type.
+import type { PreparedText, TextUnit } from "@solidrt/core"
+
+/** The anchor of the run's x: where the point sits on each line's
+ * extent (SVG's text-anchor, d-text's `anchor`). */
+export type TextAnchor = "start" | "middle" | "end"
+/** The anchor of the run's y: the top of the first line, the middle of
+ * the box, the first baseline, or the bottom of the last line. */
+export type TextAnchorY = "top" | "middle" | "baseline" | "bottom"
+/** How lines sit inside the run's width when they differ (a wrapped or
+ * multi-line run). */
+export type TextAlign = "left" | "center" | "right"
+
+export type TextLayoutOptions = {
+  /** Wrap at this width in run pixels; unset, only `\n` breaks. */
+  maxWidth?: number
+  /** Line alignment inside the run's width; default "left". */
+  align?: TextAlign
+  /** Default "start". */
+  anchor?: TextAnchor
+  /** Default "top". */
+  anchorY?: TextAnchorY
+  /** Added after every glyph, run pixels (CSS letter-spacing); default 0. */
+  letterSpacing?: number
+  /** Baseline to baseline, run pixels; default each line's own ascent
+   * plus descent. */
+  lineHeight?: number
+}
+
+/** One glyph to draw: the font's glyph id and its origin (pen x, baseline
+ * y) in run pixels from the anchor point. */
+export type GlyphPlacement = { id: number; x: number; y: number }
+
+/** One laid-out line. */
+export type TextLine = {
+  /** Unit range [from, to) into the prepared units. */
+  from: number
+  to: number
+  /** The line's x (its start after alignment) and baseline y, from the anchor point. */
+  x: number
+  y: number
+  /** Ink width (advances plus the last unit's width, trailing whitespace off). */
+  width: number
+  ascent: number
+  descent: number
+}
+
+export type TextLayout = {
+  glyphs: GlyphPlacement[]
+  lines: TextLine[]
+  /** The run's box: the widest line and the lines stacked. */
+  width: number
+  height: number
+  /** The first line's ascent: the first baseline below the box's top. */
+  ascent: number
+}
+
+/**
+ * Lay out a prepared text (from `SpriteFont.prepare`) into glyph
+ * placements. Throws on units without glyphs (a text prepared on
+ * Impeller, which exposes none).
+ */
+export function layoutText(prepared: PreparedText, opts?: TextLayoutOptions): TextLayout {
+  let units = prepared.units
+  let maxWidth = opts?.maxWidth ?? Infinity
+  if (!(maxWidth > 0)) throw new Error(`layoutText: maxWidth must be positive, got ${maxWidth}`)
+  let letterSpacing = opts?.letterSpacing ?? 0
+  if (!Number.isFinite(letterSpacing)) throw new Error(`layoutText: letterSpacing must be finite, got ${letterSpacing}`)
+  for (let i = 0; i < units.length; i++) {
+    if (units[i]!.glyphs === undefined) throw new Error(`layoutText: unit ${i} ("${units[i]!.text}") carries no glyphs; prepare the text on a sprite font`)
+  }
+  // Break into lines: the greedy pass, lines as unit ranges.
+  type Range = { from: number; to: number; ascent: number; descent: number; width: number }
+  let ranges: Range[] = []
+  let cursor = 0
+  while (cursor < units.length) {
+    ranges.push(nextLine(units, cursor, maxWidth, letterSpacing))
+    cursor = ranges[ranges.length - 1]!.to
+  }
+  // A text with no units (empty) still has one empty line of no height.
+  if (ranges.length === 0) ranges.push({ from: 0, to: 0, ascent: 0, descent: 0, width: 0 })
+  let runWidth = 0
+  for (let r of ranges) runWidth = Math.max(runWidth, r.width)
+  let lineHeight = opts?.lineHeight
+  // Stack the lines: each baseline is its ascent below the line's top.
+  let lines: TextLine[] = []
+  let top = 0
+  let align = opts?.align ?? "left"
+  for (let r of ranges) {
+    let slack = runWidth - r.width
+    let x = align === "center" ? slack / 2 : align === "right" ? slack : 0
+    let height = lineHeight ?? r.ascent + r.descent
+    lines.push({ from: r.from, to: r.to, x, y: top + r.ascent, width: r.width, ascent: r.ascent, descent: r.descent })
+    top += height
+  }
+  let height = top
+  // The anchor point's offset: what every x and y shifts by.
+  let anchor = opts?.anchor ?? "start"
+  let anchorY = opts?.anchorY ?? "top"
+  let dx = anchor === "middle" ? -runWidth / 2 : anchor === "end" ? -runWidth : 0
+  let firstAscent = lines[0]!.ascent
+  let dy = anchorY === "middle" ? -height / 2 : anchorY === "baseline" ? -firstAscent : anchorY === "bottom" ? -height : 0
+  let glyphs: GlyphPlacement[] = []
+  for (let line of lines) {
+    line.x += dx
+    line.y += dy
+    let pen = line.x
+    for (let i = line.from; i < line.to; i++) {
+      let unit = units[i]!
+      for (let g of unit.glyphs!) {
+        glyphs.push({ id: g.id, x: pen + g.x, y: line.y + g.y })
+        pen += letterSpacing
+      }
+      pen += unit.advance
+    }
+  }
+  return { glyphs, lines, width: runWidth, height, ascent: firstAscent }
+}
+
+// Ink width of the wrap unit starting at `index` (core's unitInk): its
+// advance through every glued piece after it, plus the last piece's ink,
+// with the letter spacing its glyphs add.
+function unitInk(units: TextUnit[], index: number, letterSpacing: number): number {
+  let ink = units[index]!.width + letterSpacing * units[index]!.glyphs!.length
+  let advance = 0
+  for (let j = index + 1; j < units.length && units[j]!.glue; j++) {
+    advance += units[j - 1]!.advance + letterSpacing * units[j - 1]!.glyphs!.length
+    ink = advance + units[j]!.width + letterSpacing * units[j]!.glyphs!.length
+  }
+  return ink
+}
+
+// The next line from unit `cursor` that fits `width` (core's
+// layoutNextLine): units go on while the pen plus the unit's ink stays
+// within the width; a hard break ends the line; a unit wider than the
+// line on its own goes on whole.
+function nextLine(units: TextUnit[], cursor: number, width: number, letterSpacing: number) {
+  let pen = 0
+  let ascent = 0
+  let descent = 0
+  let i = cursor
+  while (i < units.length) {
+    let unit = units[i]!
+    if (i > cursor && !unit.glue && pen + unitInk(units, i, letterSpacing) > width) break
+    pen += unit.advance + letterSpacing * unit.glyphs!.length
+    if (unit.ascent > ascent) ascent = unit.ascent
+    if (unit.descent > descent) descent = unit.descent
+    i++
+    if (unit.hardBreak) break
+  }
+  let last = units[i - 1]!
+  // The ink width: trailing whitespace off, like the unit's own `width`.
+  let lineWidth = pen - (last.advance + letterSpacing * last.glyphs!.length) + last.width + letterSpacing * last.glyphs!.length
+  return { from: cursor, to: i, ascent, descent, width: Math.max(lineWidth, 0) }
+}