@solidrt/core 0.0.69 → 0.0.71

package/agents/performance.md

@@ -102,7 +102,12 @@ Rules, in order of leverage:
    boundary node itself (or any ancestor) are hoisted out of the cache and
    applied at composite time, so animating x/y/scale/rotate/opacity of a
    boundary does NOT re-raster it (verified by A/B measurement - the damage
-   system classifies these as Transform and keeps the node's own cache).
+   system classifies these as Compose and keeps the node's own cache). One
+   exception, for crispness: a boundary holding text that comes to rest at
+   a new scale re-records once there (a snapshot boundary re-rasterizes
+   once), so its content is rasterized at the resting size instead of
+   stretched, and a scale transition with a known end rasters for that end
+   as it starts; a press scale that returns to 1 never re-rasters.
    What DOES invalidate the cache is any paint or content change inside the
    subtree - colors, path data, text, a Show toggling - so drive animation
    with transforms and keep the cached content itself static. Off a boundary,

package/examples/README.md

@@ -51,6 +51,7 @@ for the element/prop model see `@solidrt/core/AGENTS.md`.
 - `gpu-texture-blend.tsx` - compositing two shader targets as stacked `<texture>` layers with `blendMode` ("plus" additive over a base pass), the alternative to a third shader that samples both. Click toggles against `"source-over"` to show why. The tree-level counterpart to blending within one draw (`gpu-particles.tsx`); without `blend: "add"` a target's own draw runs with GL blending disabled.
 - `gpu-raw-program.tsx` - the raw shading layer: compileShader/linkProgram/createRenderPipeline/createShaderTarget, one vertex stage shared by two programs, with and without the standard header.
 - `gpu-pipeline.tsx` - `createPipelineTexture`: a custom vertex+fragment pair drawing an interleaved vertex buffer (position and color attributes resolved by name), a depth-tested spinning cube whose `uTime` uniform is driven through `<texture params>` exactly like a fragment shader's.
+- `gpu-shader-chain.tsx` - a chain of targets: a plasma `createShaderTexture` bound as a cube `createPipelineTexture`'s sampler input (`textures: { uMap: plasmaId }`). Sampler bindings are live dependencies, so the app drives only the plasma's `uTime` and the cube re-renders after it every frame, in that order, with no uniform and no per-frame code of its own. The plasma shows beside the cube on the `<texture>` that carries its params.
 - `gpu-particles.tsx` - an additive particle field: `topology: "points"` with `blend: "add"`, so overlapping gaussian splats (`gl_PointSize` from the vertex stage, `gl_PointCoord` falloff, premultiplied output) accumulate into a glowing volume instead of overwriting. The tints are typed vec3 uniforms filled from 3-number array params.
 - `gpu-instancing.tsx` - instanced drawing: one 3-vertex triangle drawn hundreds of times via `instanceCount`, each instance placed and tinted on a phyllotaxis spiral from `gl_InstanceID` alone. `setDraw(id, { instanceCount })` merges into the draw range per frame (absent keys keep their values, like params), so the population breathes without touching the buffer.
 - `gpu-draw-list.tsx` - `createDrawTarget`: one render target holding an ordered, mutable LIST of draws - two orbiting triangles from different programs sharing one depth buffer (the target owns the depth storage, each pipeline the test/write behavior), a third entry added and removed live via its stable `DrawId`, and `setDrawParams` as the per-object channel.

package/examples/gpu-shader-chain.tsx

@@ -0,0 +1,135 @@
+// A chain of targets: a plasma fragment pass feeding a cube pipeline that
+// samples it. Sampler bindings are live dependencies (the model in
+// @solidrt/core/docs/reference/gpu.md): the cube's target is bound to the
+// plasma's through `textures`, so whenever the plasma re-renders, the cube
+// re-renders after it in the same frame, in that order. The app therefore
+// drives only the first pass: the plasma's uTime through the <texture>
+// params prop, as in gpu-shader.tsx. The cube has no uniform of its own
+// and no per-frame code; its view is fixed in the vertex shader, and its
+// faces move because what they sample moves.
+//
+// The plasma is shown beside the cube because that <texture> is where its
+// params prop lives. A source pass that is not on screen is driven the same
+// way from any <texture> of its id. The cube's buffers and index buffer are
+// the gpu-pipeline.tsx mesh with a UV per corner in place of a color.
+import { render, onFrame, createSignal } from "@solidrt/core"
+import { createBuffer, createPipelineTexture, createShaderTexture, glsl } from "@solidrt/core/gpu"
+
+// The plasma target's side: what the cube's faces sample.
+let PLASMA_SIZE = 256
+// The cube target's side: what the window shows.
+let CUBE_SIZE = 512
+
+// Pass 1: a plasma, the only thing the app animates.
+let PLASMA = glsl`
+  uniform float uTime;
+  void main() {
+    vec2 uv = vUV * 6.0;
+    float t = uTime;
+    float v = sin(uv.x + t) + sin(uv.y + t * 0.8) + sin((uv.x + uv.y) * 0.7 + t * 1.3)
+      + sin(length(uv - 3.0) * 1.5 - t);
+    vec3 col = 0.5 + 0.5 * cos(v * 1.2 + vec3(0.0, 2.1, 4.2));
+    fragColor = vec4(col, 1.0);
+  }
+`
+
+// Pass 2: the cube, viewed from one fixed angle. The projection rig and the
+// clip-y flip are gpu-pipeline.tsx's.
+let VERTEX = glsl`
+  in vec3 aPos;
+  in vec2 aUV;
+  out vec2 vTex;
+
+  void main() {
+    float cy = cos(0.7), sy = sin(0.7);
+    float cx = cos(0.5), sx = sin(0.5);
+    mat3 rotY = mat3(cy, 0.0, -sy, 0.0, 1.0, 0.0, sy, 0.0, cy);
+    mat3 rotX = mat3(1.0, 0.0, 0.0, 0.0, cx, sx, 0.0, -sx, cx);
+    vec3 p = rotX * (rotY * aPos);
+    p.z -= 2.5;
+    float w = -p.z;
+    float f = 2.0;
+    float a = 11.0 / 9.0;
+    float b = -20.0 / 9.0;
+    gl_Position = vec4(p.x * f, -p.y * f, w * a + b, w);
+    vTex = aUV;
+  }
+`
+
+// The sampler is the chain: uMap is bound to the plasma target below.
+let FRAGMENT = glsl`
+  in vec2 vTex;
+  uniform sampler2D uMap;
+  void main() {
+    fragColor = texture(uMap, vTex);
+  }
+`
+
+// Interleaved [pos vec3, uv vec2]: 24 vertices, 4 per face, each face the
+// whole plasma once. Every face winds counter-clockwise seen from outside.
+function cubeVertices(): Float32Array {
+  type Vec3 = [number, number, number]
+  let verts: number[] = []
+  let quad = (a: Vec3, b: Vec3, c: Vec3, d: Vec3) => {
+    let uvs = [[0, 1], [1, 1], [1, 0], [0, 0]]
+    for (let [i, p] of [a, b, c, d].entries()) verts.push(p[0], p[1], p[2], uvs[i]![0]!, uvs[i]![1]!)
+  }
+  let s = 0.5
+  quad([-s, -s, s], [s, -s, s], [s, s, s], [-s, s, s]) // front
+  quad([s, -s, -s], [-s, -s, -s], [-s, s, -s], [s, s, -s]) // back
+  quad([s, -s, s], [s, -s, -s], [s, s, -s], [s, s, s]) // right
+  quad([-s, -s, -s], [-s, -s, s], [-s, s, s], [-s, s, -s]) // left
+  quad([-s, s, s], [s, s, s], [s, s, -s], [-s, s, -s]) // top
+  quad([-s, -s, -s], [s, -s, -s], [s, -s, s], [-s, -s, s]) // bottom
+  return new Float32Array(verts)
+}
+
+// Two triangles per face over its 4 shared vertices: 36 uint16 indices.
+function cubeIndices(): Uint16Array {
+  let indices: number[] = []
+  for (let face = 0; face < 6; face++) {
+    let v = face * 4
+    indices.push(v, v + 1, v + 2, v, v + 2, v + 3)
+  }
+  return new Uint16Array(indices)
+}
+
+function App() {
+  let plasmaId = createShaderTexture(PLASMA, PLASMA_SIZE, PLASMA_SIZE, { uTime: 0 }, { label: "plasma" })
+  let bufferId = createBuffer(cubeVertices(), { label: "cube-verts" })
+  let indexId = createBuffer(cubeIndices(), { label: "cube-indices" })
+  // No params: nothing of the cube's is ever written. Its one input is the
+  // plasma target, and that binding is what re-renders it.
+  let cubeId = createPipelineTexture(VERTEX, FRAGMENT, CUBE_SIZE, CUBE_SIZE, null, {
+    label: "cube",
+    textures: { uMap: plasmaId },
+    buffers: [
+      {
+        attributes: [
+          { name: "aPos", format: "float32x3" },
+          { name: "aUV", format: "float32x2" },
+        ],
+        buffer: bufferId,
+      },
+    ],
+    indexBuffer: indexId,
+    indexFormat: "uint16",
+    depth: true,
+    cull: "back",
+    clearColor: [0.08, 0.08, 0.12, 1],
+  })
+  let [time, setTime] = createSignal(0)
+  onFrame((tick) => setTime(tick / 1000))
+
+  return (
+    <window alignItems="center" justifyContent="center" flexDirection="row" gap={24}>
+      <texture src={cubeId} width={CUBE_SIZE} height={CUBE_SIZE} />
+      <view flexDirection="column" alignItems="center" gap={8}>
+        <texture src={plasmaId} params={{ uTime: time() }} width={PLASMA_SIZE} height={PLASMA_SIZE} />
+        <text fontSize={14} color="#888">the plasma pass, the only one driven</text>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/core",
-  "version": "0.0.69",
+  "version": "0.0.71",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -33,8 +33,8 @@
     "AGENTS.md"
   ],
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.69",
-    "@solidrt/test": "0.0.69"
+    "@solidrt/flux-types": "0.0.71",
+    "@solidrt/test": "0.0.71"
   },
   "peerDependencies": {
     "@solidjs/signals": "2.0.0-rc.13",

package/src/core.ts

@@ -391,15 +391,42 @@ export function prepareText(text: string, options?: tree.MeasureTextOptions): tr
 }
 
 /**
- * Makes the glyph cells of printable ASCII for these font styles ahead of
- * their first use, off the frame: call it at startup with the type scale
- * the app draws in (the components' Window does it for the theme's), so a
- * screen's first paint in any of them never waits for cells. Glyphs outside
- * ASCII are made at first use. Each entry names a font as a <text> would;
- * line height and maxLines are ignored.
+ * Makes glyph cells ahead of their first use, off the frame: call it at
+ * startup with the type scale the app draws in (the components' Window
+ * does it for the theme's), so a screen's first paint in any of them never
+ * waits for cells. Each entry names a font as a <text> would (line height
+ * and maxLines are ignored) and warms its printable ASCII; an entry with a
+ * `text` also warms the glyphs that string shapes to in the font (a
+ * ligature, a curly quote, a letter beyond ASCII), so a headline or a
+ * label the app knows it will draw is warm too. Anything else is made at
+ * first use.
  */
-export function warmText(styles: tree.MeasureTextOptions[]): void {
-  tree.warmText(styles)
+export function warmText(entries: tree.WarmTextEntry[]): void {
+  tree.warmText(entries)
+}
+
+export type TextRenderingOptions = tree.TextRenderingOptions
+export type TextRenderingPolicy = tree.TextRenderingPolicy
+
+/**
+ * Changes how every text is rendered: the coverage-to-color mode and its
+ * gamma or contrast, and the stem darkening and hinting of the glyph cells. Each option
+ * given replaces its part of the current policy, the rest stays; every text
+ * redraws at the next frame. The defaults are what an app that says nothing
+ * gets; this is the knob for judging a policy by eye on a running app.
+ */
+export function setTextRendering(options: TextRenderingOptions): void {
+  tree.setTextRendering(options)
+}
+
+/**
+ * The text rendering policy as it stands, resolved for this display: the
+ * shape setTextRendering takes, with a darkening or hinting left at its
+ * default read as the value the display scale gives it. What a settings
+ * screen shows; setting it back changes nothing on this display.
+ */
+export function textRendering(): TextRenderingPolicy {
+  return tree.textRendering()
 }
 
 /** One laid-out line from layoutNextLine. */
@@ -426,6 +453,13 @@ export type TextLine = {
  * every glued piece that follows, plus the last piece's ink. What must fit on
  * the line for the unit to go on it.
  */
+// Slack a line's width may be exceeded by and still fit, logical px: the
+// width a laid-out box hands back is a float ulp off the width its text
+// measured (the rendertree's layout::FIT_SLACK, the same value), so an
+// exact fit wraps a word inside its own box. 1/64 px is a browser layout
+// unit: far above any ulp drift, far below a visible overhang.
+export const FIT_SLACK = 1 / 64
+
 export function unitInk(units: tree.TextUnit[], index: number): number {
   let ink = units[index]!.width
   let advance = 0
@@ -439,7 +473,8 @@ export function unitInk(units: tree.TextUnit[], index: number): number {
 /**
  * The next line of `prepared` from unit `cursor` that fits `width`, or null
  * when the text is used up. Greedy: units go on the line while the pen plus
- * the unit's ink stays within `width`; a hard break ends the line; a unit
+ * the unit's ink stays within `width` (a hair of slack for float drift
+ * included); a hard break ends the line; a unit
  * wider than `width` on its own goes on the line whole and overflows. Draw a
  * line as `<d-text x y w={line.width + 1}>{prepared.text.slice(line.start, line.end)}</d-text>`
  * with the same font options; its words are already shaped, so that is
@@ -458,7 +493,7 @@ export function layoutNextLine(prepared: tree.PreparedText, cursor: number, widt
     let unit = units[i]!
     // Glued pieces stay with the unit they continue: the whole wrap unit
     // (this piece through the last glued one) must fit for any of it to go on.
-    if (i > cursor && !unit.glue && pen + unitInk(units, i) > width) break
+    if (i > cursor && !unit.glue && pen + unitInk(units, i) > width + FIT_SLACK) break
     pen += unit.advance
     if (unit.ascent > ascent) ascent = unit.ascent
     if (unit.descent > descent) descent = unit.descent

package/src/gpu.ts

@@ -753,6 +753,128 @@ export function writeBuffer(id: gpu.BufferId, data: ArrayBuffer | ArrayBufferVie
   gpu.writeBuffer(id, toUint8(data), byteOffset)
 }
 
+/**
+ * A stream of fixed-size records with a GPU buffer, a CPU mirror and a
+ * dirty range: the publish model shared by every JS-stepped population
+ * (a 2d sprite layer's records, a 3d mesh's instance streams). Write the
+ * mirror, `mark` the records written, then `publish` at the flush: the
+ * dirty range goes out as one `writeBuffer` at its byte offset, or the
+ * drawn prefix whole through the write lease when the buffer carries an
+ * instance order (the engine gathers the copy into key order, and a byte
+ * range has no stable position under a permutation). Growth replaces the
+ * buffer and the mirror (never a resize) and marks what the mirror held,
+ * so the next publish fills the replacement; the old buffer is the
+ * caller's to destroy once nothing binds it. Read `buffer` and `bytes` at
+ * use time: both are replaced by growth.
+ */
+export type RecordStream = {
+  /** The GPU buffer the records publish to; replaced by `grow`. */
+  readonly buffer: gpu.BufferId
+  /** The mirror, `capacity * stride` bytes; replaced by `grow`. View it as
+   * the record layout wants (a Float32Array over it for an all-float
+   * record). */
+  readonly bytes: Uint8Array<ArrayBuffer>
+  /** Bytes per record. */
+  readonly stride: number
+  /** Records the mirror and the buffer hold. */
+  readonly capacity: number
+  /** Whether any record is marked since the last publish. */
+  readonly dirty: boolean
+  /** Extend the dirty range over records [first, last). */
+  mark(first: number, last: number): void
+  /** Send what is dirty and clear the mark. `whole`: the first `limit`
+   * records go out through the lease regardless of the range (the
+   * ordered form, and a replacement buffer's first fill); otherwise the
+   * dirty range, clipped to `limit` records (the live sprites, or the
+   * capacity when records are written ahead of their count). Nothing is
+   * sent for an empty range or a zero `limit`. */
+  publish(whole: boolean, limit: number): void
+  /** Replace the buffer and the mirror with room for `capacity` records,
+   * the old contents copied over and marked whole; returns the OLD buffer
+   * for the caller to destroy once its draws point at the new one. */
+  grow(capacity: number): gpu.BufferId
+  /** Free the buffer. Safe to call more than once. */
+  destroy(): void
+}
+
+/**
+ * Creates a record stream of `capacity` records of `stride` bytes (see
+ * {@link RecordStream}): a sized, unwritten GPU buffer and a zeroed
+ * mirror. Freed with the reactive owner like a buffer (opt out with
+ * `{ autoFree: false }` and call `destroy`).
+ */
+export function createRecordStream(stride: number, capacity: number, opts?: CreateOptions): RecordStream {
+  if (!(Number.isInteger(stride) && stride > 0)) throw new Error("createRecordStream: stride must be a positive integer, got " + stride)
+  if (!(Number.isInteger(capacity) && capacity > 0)) throw new Error("createRecordStream: capacity must be a positive integer, got " + capacity)
+  let buffer = createBuffer(capacity * stride, { label: opts?.label, autoFree: false })
+  let bytes = new Uint8Array(capacity * stride)
+  let dirty: [number, number] | null = null
+  let destroyed = false
+  let stream: RecordStream = {
+    get buffer() {
+      return buffer
+    },
+    get bytes() {
+      return bytes
+    },
+    stride,
+    get capacity() {
+      return bytes.length / stride
+    },
+    get dirty() {
+      return dirty !== null
+    },
+    mark(first, last) {
+      let capacity = bytes.length / stride
+      if (!Number.isInteger(first) || !Number.isInteger(last) || first < 0 || last > capacity || first > last) {
+        throw new Error("RecordStream.mark: range [" + first + ", " + last + ") is outside the stream's " + capacity + " records")
+      }
+      if (first === last) return
+      if (dirty === null) dirty = [first, last]
+      else {
+        if (first < dirty[0]) dirty[0] = first
+        if (last > dirty[1]) dirty[1] = last
+      }
+    },
+    publish(whole, limit) {
+      let range = dirty
+      dirty = null
+      if (whole) {
+        let byteLength = Math.min(limit, bytes.length / stride) * stride
+        if (byteLength <= 0) return
+        let out = beginBufferWrite(buffer)
+        new Uint8Array(out.buffer, 0, byteLength).set(bytes.subarray(0, byteLength))
+        gpu.endBufferWrite(buffer, byteLength)
+        return
+      }
+      if (range === null) return
+      let lo = range[0]
+      let hi = Math.min(range[1], limit)
+      if (hi > lo) writeBuffer(buffer, bytes.subarray(lo * stride, hi * stride), lo * stride)
+    },
+    grow(next) {
+      let previous = bytes.length / stride
+      if (!(Number.isInteger(next) && next > previous)) {
+        throw new Error("RecordStream.grow: capacity must be an integer above the current " + previous + ", got " + next)
+      }
+      let old = buffer
+      buffer = createBuffer(next * stride, { label: opts?.label, autoFree: false })
+      let grown = new Uint8Array(next * stride)
+      grown.set(bytes)
+      bytes = grown
+      dirty = [0, previous]
+      return old
+    },
+    destroy() {
+      if (destroyed) return
+      destroyed = true
+      gpu.destroyBuffer(buffer)
+    },
+  }
+  if (opts?.autoFree !== false && getOwner()) onCleanup(() => stream.destroy())
+  return stream
+}
+
 /**
  * Hands an ordered instance buffer's full record set to the engine - the
  * write-once form: the engine keeps the one CPU copy and sorts,

package/src/index.ts

@@ -1,6 +1,6 @@
 export * from "./renderer"
-export { setFocus, focusedNode, startTextInput, textInputActive, getFocusables, measureText, prepareText, warmText, layoutNextLine, unitInk, getBoundingBox, getBoundingBoxViewport, getLayoutBox, snapshotTexture, onPointerMove } from "./core"
-export type { BoundingBox, GlobalPointerEvent, TextLine } from "./core"
+export { setFocus, focusedNode, startTextInput, textInputActive, getFocusables, measureText, prepareText, warmText, setTextRendering, textRendering, layoutNextLine, unitInk, getBoundingBox, getBoundingBoxViewport, getLayoutBox, snapshotTexture, onPointerMove } from "./core"
+export type { BoundingBox, GlobalPointerEvent, TextLine, TextRenderingOptions, TextRenderingPolicy } from "./core"
 export { parseColor, mixColors, withAlpha, brightness, createLinearGradient, createRadialGradient } from "./color"
 export type { Gradient, GradientStop } from "./color"
 export { onFrame, frameTime, onBeforeRender, onLayout, onResize, onWindowFocus, onWindowBlur, onBack, onLink, onSuspend, onQuit, exit, background, registerProtocolHandler } from "./window"
@@ -25,6 +25,7 @@ export { Logo } from "./logo"
 export type { LogoProps } from "./logo"
 export type { SvgDocument, SvgDraw } from "./svg"
 export { createScroll } from "./scroll"
+export { warnOnce } from "./warn"
 export type { Scroll, ScrollAxis, ScrollBehavior, ScrollOffset, ScrollOptions, ScrollToOptions } from "./scroll"
 export { arena } from "./arena"
 export type { ArenaOwner } from "./arena"
@@ -93,7 +94,7 @@ export type {
   Color,
   Pct,
 } from "./types"
-export type { MeasureTextOptions, PreparedText, TextRunRange, TextUnit } from "flux:rendertree"
+export type { MeasureTextOptions, PreparedText, TextRunRange, TextUnit, WarmTextEntry } from "flux:rendertree"
 
 // A percentage value for dimensional props (e.g. transformOrigin): `pct(50)` is
 // half the element box. Keeps percentages a first-class branded value rather

package/src/scroll.ts

@@ -7,6 +7,7 @@
 import { createSignal } from "@solidjs/signals"
 import { getBoundingBox } from "./core"
 import { onLayout } from "./window"
+import { warnOnce } from "./warn"
 
 export type ScrollAxis = "vertical" | "horizontal" | "both"
 
@@ -75,11 +76,9 @@ export function createScroll(
 
   // A scroll viewport with no explicit main-axis size resolves to 0 in flex
   // layout and its content silently vanishes - a classic trap (maxHeight alone
-  // does not size it either). Detect it at measure time and warn once, with a
-  // stack captured at creation so the warning points at the component that
-  // built the scroller (the dev server remaps the frames to .tsx).
-  let origin = new Error().stack ?? ""
-  let warnedCollapsed = false
+  // does not size it either). Detect it at measure time and warn once, from
+  // the component that built the scroller (warnOnce captures its stack here).
+  let warnCollapsed = warnOnce()
 
   // Last measured overflow, refreshed each layout. scrollBy/scrollTo clamp
   // against these between layouts; onLayout re-clamps once new sizes are known.
@@ -110,17 +109,14 @@ export function createScroll(
     let vb = getBoundingBox(vp)
     let cb = getBoundingBox(ct)
     if (!vb || !cb) return
-    if (!warnedCollapsed) {
-      let zeroY = canY && vb.height === 0 && cb.height > 0
-      let zeroX = canX && vb.width === 0 && cb.width > 0
-      if (zeroY || zeroX) {
-        warnedCollapsed = true
-        let axisName = zeroY ? "height" : "width"
-        console.warn(
-          `Scroll container resolved to ${axisName} 0, so its content is invisible. ` +
-            `Give it an explicit ${axisName} or flex; maxHeight/maxWidth alone does not size it.\n${origin}`,
-        )
-      }
+    let zeroY = canY && vb.height === 0 && cb.height > 0
+    let zeroX = canX && vb.width === 0 && cb.width > 0
+    if (zeroY || zeroX) {
+      let axisName = zeroY ? "height" : "width"
+      warnCollapsed(
+        `Scroll container resolved to ${axisName} 0, so its content is invisible. ` +
+          `Give it an explicit ${axisName} or flex; maxHeight/maxWidth alone does not size it.`,
+      )
     }
     maxX = Math.max(0, cb.width - vb.width)
     maxY = Math.max(0, cb.height - vb.height)

package/src/text-input.ts

@@ -5,7 +5,7 @@
 // are policy and belong to the component (the "skin") that composes these.
 
 import { createMemo, createSignal, flush, untrack } from "@solidjs/signals"
-import { getLayoutBox, layoutNextLine, measureText, prepareText, unitInk } from "./core"
+import { FIT_SLACK, getLayoutBox, layoutNextLine, measureText, prepareText, unitInk } from "./core"
 import type { MeasureTextOptions, PreparedText, TextRunRange, TextUnit } from "flux:rendertree"
 import { onLayout } from "./window"
 
@@ -542,12 +542,12 @@ export function createTextEditorLayout(
 // through as is.
 function splitWide(prepared: PreparedText, width: number): PreparedText {
   let all = prepared.units
-  if (!all.some((u, i) => !u.glue && unitInk(all, i) > width)) return prepared
+  if (!all.some((u, i) => !u.glue && unitInk(all, i) > width + FIT_SLACK)) return prepared
   let wide = false
   let units: TextUnit[] = []
   for (let u = 0; u < all.length; u++) {
     let unit = all[u]!
-    if (!unit.glue) wide = unitInk(all, u) > width
+    if (!unit.glue) wide = unitInk(all, u) > width + FIT_SLACK
     let stops = unit.carets
     if (!wide || !stops || stops.length <= 2) {
       units.push(unit)

package/src/types.d.ts

@@ -103,6 +103,21 @@ export interface LayoutProps extends FlexboxProps, GridProps {
    * resolves against whatever relative element is above all of them.
    */
   position?: "relative" | "absolute"
+  /**
+   * CSS size containment: the element sizes as if it had no content. A
+   * texture or text measures as zero on every axis layout does not hand it,
+   * and a view's children add nothing to its box; they lay out inside
+   * whatever box it gets. The one CSS `contain` value with a meaning here.
+   * The element still needs a size from its own props or its parent (a
+   * `flexGrow` in a sized column), or it comes out empty.
+   *
+   * What takes the place of the web's `minHeight={0}` escape from the flex
+   * automatic minimum, declared on the element whose content would
+   * otherwise pin its ancestors: a fill-mode `<Scene>` or `<SpriteLayer>`
+   * leaf sets it, so the target that follows the leaf's box never feeds its
+   * pixel size back into layout.
+   */
+  contain?: "size"
 
   top?: Dimension
   right?: Dimension

package/src/warn.ts

@@ -0,0 +1,22 @@
+// A development warning for a misuse that shows later than the code that
+// caused it: a layout that comes out empty, an event that never arrives. The
+// site of the misuse is the component that built the thing, not the layout
+// pass that notices, so the warning carries that component's stack.
+
+/**
+ * A once-only dev warning bound to the place it is created: `let warn =
+ * warnOnce()` where a component builds something whose misuse surfaces
+ * later (a scroller, a fill-mode scene), `warn(message)` from the layout
+ * or event read that notices. The first call reports, with the stack of the
+ * creation site under the message (the dev server remaps the frames to
+ * .tsx); later calls are silent.
+ */
+export function warnOnce(): (message: string) => void {
+  let origin = new Error().stack ?? ""
+  let warned = false
+  return message => {
+    if (warned) return
+    warned = true
+    console.warn(`${message}\n${origin}`)
+  }
+}