Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(text): TextOverflow does what its dropdown says

esengine5537746ec627
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 03e116c58..ab4a5722a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -98,10 +98,24 @@ published separately; it ships inside the editor.
for started/ended and no write door at all. Freezing either would freeze the
gaps in it.
-- **`TextData.overflow` is labelled as not implemented.** The Inspector offered a
- Clip / Ellipsis / Visible dropdown for a field that no layout or render path
- reads, so every value drew as Visible with no warning. The field, its type and
- the Inspector label now all say so; the truncation itself is still to come.
+- **`TextData.overflow` does something.** The Inspector offered a Clip / Ellipsis
+ / Visible dropdown for a field that no layout or render path read, so every value
+ drew as Visible with no warning. Both modes now drop the lines past the box
+ height and trim a line past its width, with Ellipsis marking the cut. Two
+ details are the contract rather than the implementation: a box too short for one
+ line still shows one, because nothing is not an answer a reader can act on; and
+ the mark goes on the last kept line whenever lines were dropped, even if that
+ line fits, because it says "there is more" and not "this line was long".
+ Trimming is whole-glyph — text does not go through a scissor.
+
+ Rich text truncates by line only. Trimming one means measuring per run, and a
+ run carries its own size and style.
+
+ Twelve assertions on the pure layout, and a pixel gate that is a differential:
+ two identical labels in identical one-line boxes, Visible beside Clip, so a
+ truncation that silently does nothing leaves both second lines drawn and the
+ pair says so. Making the truncation a no-op turns it red, which is what makes it
+ a gate rather than a screenshot.
- **`examples/input-actions` demonstrates every binding kind it renders.** Its
`formatBinding` switched on all eight while the project could construct four. It
diff --git a/desktop/public/scenes/ui-text-overflow.esscene b/desktop/public/scenes/ui-text-overflow.esscene
new file mode 100644
index 000000000..cdec30574
--- /dev/null
+++ b/desktop/public/scenes/ui-text-overflow.esscene
@@ -0,0 +1,95 @@
+{
+ "version": "1.0",
+ "name": "TextOverflow — Visible beside Clip",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 10 } } },
+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 300, "isActive": true, "priority": 0 } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 1,
+ "name": "Canvas",
+ "parent": null,
+ "children": [2, 3],
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "Canvas", "data": { "designResolution": { "x": 800, "y": 600 }, "scaleMode": 2 } },
+ { "type": "UINode", "data": {} }
+ ],
+ "visible": true
+ },
+ {
+ "id": 2,
+ "name": "Spills",
+ "parent": 1,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": {} },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "width": { "value": 300.0, "unit": 0 },
+ "height": { "value": 100.0, "unit": 0 },
+ "insetLeft": { "value": 30.0, "unit": 0 },
+ "insetTop": { "value": 60.0, "unit": 0 }
+ }
+ },
+ {
+ "type": "Text",
+ "data": {
+ "content": "HHH\nHHH\nHHH",
+ "fontFamily": "sans-serif",
+ "fontSize": 90,
+ "color": { "r": 1, "g": 1, "b": 1, "a": 1 },
+ "align": 0,
+ "verticalAlign": 0,
+ "wordWrap": false,
+ "overflow": 0
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 3,
+ "name": "Clipped",
+ "parent": 1,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": {} },
+ {
+ "type": "UINode",
+ "data": {
+ "position": 1,
+ "width": { "value": 300.0, "unit": 0 },
+ "height": { "value": 100.0, "unit": 0 },
+ "insetLeft": { "value": 430.0, "unit": 0 },
+ "insetTop": { "value": 60.0, "unit": 0 }
+ }
+ },
+ {
+ "type": "Text",
+ "data": {
+ "content": "HHH\nHHH\nHHH",
+ "fontFamily": "sans-serif",
+ "fontSize": 90,
+ "color": { "r": 1, "g": 1, "b": 1, "a": 1 },
+ "align": 0,
+ "verticalAlign": 0,
+ "wordWrap": false,
+ "overflow": 1
+ }
+ }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 56c2bbb4c..5a9ce1b5a 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -1,9 +1,9 @@
{
"note": "Generated by tools/api-stability.mjs from sdk/etc/*.api.md — do not edit.",
"counts": {
- "public": 111,
+ "public": 112,
"beta": 60,
- "experimental": 1459,
+ "experimental": 1458,
"deprecated": 3
},
"total": 1630,
@@ -1334,6 +1334,18 @@
"minigame"
]
},
+ {
+ "name": "TextOverflow",
+ "kind": "type",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "TextRenderMode",
"kind": "type",
diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.json
index b9a9ce22c..484096e86 100644
--- a/docs/astro/src/data/components.generated.json
+++ b/docs/astro/src/data/components.generated.json
@@ -2857,7 +2857,7 @@
"key": "overflow",
"type": "enum",
"default": "Visible",
- "doc": "Not honoured yet: nothing reads this field, so every value renders as Visible. Shown so the data a scene already carries stays editable.",
+ "doc": "What text too big for its box does. Needs a layout box: Clip and Ellipsis drop the lines past its height and trim a line past its width.",
"values": [
"Visible",
"Clip",
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index eca6337f9..47c9ef58d 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 111 public · 53 beta · 1344 experimental · 3 deprecated
+Symbols: 112 public · 53 beta · 1343 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -7144,7 +7144,7 @@ lineCount: number
width: number
```
-## TextOverflow — type @experimental
+## TextOverflow — type @public
```
(typeof TextOverflow)[keyof typeof TextOverflow]
```
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 4b1b2b8b9..91c14d475 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.native
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 111 public · 58 beta · 1363 experimental · 3 deprecated
+Symbols: 112 public · 58 beta · 1362 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -7337,7 +7337,7 @@ lineCount: number
width: number
```
-## TextOverflow — type @experimental
+## TextOverflow — type @public
```
(typeof TextOverflow)[keyof typeof TextOverflow]
```
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 437a634e8..8e6814740 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 111 public · 55 beta · 1343 experimental · 3 deprecated
+Symbols: 112 public · 55 beta · 1342 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -7139,7 +7139,7 @@ lineCount: number
width: number
```
-## TextOverflow — type @experimental
+## TextOverflow — type @public
```
(typeof TextOverflow)[keyof typeof TextOverflow]
```
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index c488afeab..dfa33d4a1 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/minigame
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 111 public · 53 beta · 1364 experimental · 3 deprecated
+Symbols: 112 public · 53 beta · 1363 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -7384,7 +7384,7 @@ lineCount: number
width: number
```
-## TextOverflow — type @experimental
+## TextOverflow — type @public
```
(typeof TextOverflow)[keyof typeof TextOverflow]
```
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index cd7f1f3fa..0f5e03750 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 111 public · 53 beta · 1354 experimental · 3 deprecated
+Symbols: 112 public · 53 beta · 1353 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -7146,7 +7146,7 @@ lineCount: number
width: number
```
-## TextOverflow — type @experimental
+## TextOverflow — type @public
```
(typeof TextOverflow)[keyof typeof TextOverflow]
```
diff --git a/sdk/src/ui/core/text.ts b/sdk/src/ui/core/text.ts
index dc1f43bbd..068502ff6 100644
--- a/sdk/src/ui/core/text.ts
+++ b/sdk/src/ui/core/text.ts
@@ -32,16 +32,19 @@ export const TextVerticalAlign = {
export type TextVerticalAlign = (typeof TextVerticalAlign)[keyof typeof TextVerticalAlign];
/**
- * What a run too big for its box does — NOT HONOURED YET. No layout or render
- * path reads {@link TextData.overflow}, so every value behaves as `Visible`.
- * Unfrozen for that reason: freezing it would promise a behaviour that does not
- * exist.
+ * What a run too big for its box does. Needs a box: `Clip` and `Ellipsis` drop the
+ * lines past the box height, and trim a line past the box width. Trimming is
+ * whole-glyph — text does not go through a scissor, so a partial glyph is not
+ * something this can draw.
+ *
+ * @public
*/
export const TextOverflow = {
Visible: 0,
Clip: 1,
Ellipsis: 2,
} as const;
+/** @public */
export type TextOverflow = (typeof TextOverflow)[keyof typeof TextOverflow];
/** Glyph pipeline for a Text.
@@ -88,7 +91,6 @@ export interface TextData {
align: TextAlign;
verticalAlign: TextVerticalAlign;
wordWrap: boolean;
- /** Not honoured yet — see {@link TextOverflow}. Stored and ignored. */
overflow: TextOverflow;
lineHeight: number;
bold: boolean;
@@ -168,8 +170,7 @@ export const Text = defineComponent<TextData>('Text', {
verticalAlign: { enum: enumOptions(TextVerticalAlign), tooltip: 'Vertical alignment: within the layout box when the entity has a UINode, else it anchors the text to the entity origin (top/middle/bottom).' },
overflow: {
enum: enumOptions(TextOverflow),
- label: 'Overflow (not implemented)',
- tooltip: 'Not honoured yet: nothing reads this field, so every value renders as Visible. Shown so the data a scene already carries stays editable.',
+ tooltip: 'What text too big for its box does. Needs a layout box: Clip and Ellipsis drop the lines past its height and trim a line past its width.',
},
renderMode: { enum: enumOptions(TextRenderMode) },
layer: { tooltip: 'Draw layer for a text standing in the WORLD (no UINode) — read like Sprite/ShapeRenderer layer, so a label can sit in front of the content around it. Ignored inside a Canvas, where the UI render order decides.' },
diff --git a/sdk/src/ui/text/layout.ts b/sdk/src/ui/text/layout.ts
index 25ddae347..a3bbf624c 100644
--- a/sdk/src/ui/text/layout.ts
+++ b/sdk/src/ui/text/layout.ts
@@ -176,6 +176,44 @@ export interface MultilineTextOptions extends TextLayoutOptions {
* horizontal align work inside a fixed box even when word-wrap is off.
*/
boxWidth?: number;
+ /** Height (display px) of the layout box, for {@link overflow}. 0/undefined =
+ * no box, so nothing can overflow one. */
+ boxHeight?: number;
+ /**
+ * What a run too big for the box does: 0 visible (default), 1 clip, 2
+ * ellipsis. Needs `boxHeight` to drop lines and a width to trim one.
+ */
+ overflow?: number;
+}
+
+/** {@link MultilineTextOptions.overflow} — mirrors the TextOverflow const. */
+export const TEXT_OVERFLOW_VISIBLE = 0;
+export const TEXT_OVERFLOW_CLIP = 1;
+export const TEXT_OVERFLOW_ELLIPSIS = 2;
+
+/** The character appended to a line the ellipsis mode cut. */
+const ELLIPSIS = '\u2026';
+
+/**
+ * Cut `line` down to `limit` px, appending an ellipsis when asked. Trimmed one
+ * code point at a time from the end rather than by a ratio: a proportional guess
+ * lands mid-glyph on any font that is not monospace, and the ellipsis has to fit
+ * INSIDE the limit or the trim it paid for was for nothing.
+ */
+function truncateLine(
+ line: string, measure: (s: string) => number, limit: number, ellipsis: boolean,
+): string {
+ if (limit <= 0 || measure(line) <= limit) return line;
+ const tail = ellipsis ? ELLIPSIS : '';
+ const chars = [...line];
+ // Whole-glyph granularity, and the caller is told so: a partial glyph would
+ // need the renderer to scissor, which text does not go through.
+ while (chars.length > 0) {
+ chars.pop();
+ const candidate = chars.join('').trimEnd();
+ if (measure(candidate + tail) <= limit) return candidate + tail;
+ }
+ return tail;
}
/** Sum of glyph advances for a string at the given size (display px). Pure. */
@@ -264,17 +302,52 @@ export function layoutText(
// Word-wrap before stacking; explicit \n still hard-breaks. Rich lines wrap
// at the styled-run level so a token measures with its own size/style. Inline
// images survive the no-wrap path; wrapping is text-only (images drop) for now.
- const lineLayouts = opts.rich
- ? rawLines
- .map(l => parseRichText(l))
- .flatMap(runs => (wrap
- ? wrapRichRuns(runs.filter((r): r is TextSegment => r.type === 'text'), atlas, fontFamily, opts.fontSizePx, style, opts.maxWidth!, opts.letterSpacing ?? 0)
- : [runs]))
- .map(runs => layoutRichRuns(runs, atlas, fontFamily, richOpts, style))
- : (wrap
- ? rawLines.flatMap(l => wrapLine(l, atlas, fontFamily, opts.fontSizePx, style, opts.maxWidth!, opts.letterSpacing ?? 0))
- : rawLines
- ).map(line => layoutLine(line, atlas, fontFamily, opts, style));
+ // How many lines the box has room for. Below Visible only, and never zero: a
+ // box too short for one line shows one clipped line rather than nothing, which
+ // is what every layout engine does and what a reader can act on.
+ const overflow = opts.overflow ?? TEXT_OVERFLOW_VISIBLE;
+ const boxHeight = opts.boxHeight ?? 0;
+ const maxLines = overflow !== TEXT_OVERFLOW_VISIBLE && boxHeight > 0
+ ? Math.max(1, Math.floor(boxHeight / lineHeight))
+ : Infinity;
+ const ellipsis = overflow === TEXT_OVERFLOW_ELLIPSIS;
+ // The width a line may not exceed. maxWidth already wrapped to it, so this is
+ // for the unwrapped case — a single line in a fixed box, which is the one
+ // ellipsis is usually asked for.
+ const widthLimit = overflow === TEXT_OVERFLOW_VISIBLE ? 0
+ : (opts.maxWidth && opts.maxWidth > 0) ? opts.maxWidth
+ : (opts.boxWidth ?? 0);
+
+ let lineLayouts: TextLayout[];
+ if (opts.rich) {
+ // Rich text truncates by line only: trimming one means measuring per run,
+ // and a run's own size and style make that a different calculation.
+ const richLines = rawLines
+ .map(l => parseRichText(l))
+ .flatMap(runs => (wrap
+ ? wrapRichRuns(runs.filter((r): r is TextSegment => r.type === 'text'), atlas, fontFamily, opts.fontSizePx, style, opts.maxWidth!, opts.letterSpacing ?? 0)
+ : [runs]));
+ const kept = richLines.slice(0, maxLines === Infinity ? undefined : maxLines);
+ if (ellipsis && kept.length < richLines.length && kept.length > 0) {
+ kept[kept.length - 1] = [...kept[kept.length - 1], { type: 'text', text: ELLIPSIS } as TextSegment];
+ }
+ lineLayouts = kept.map(runs => layoutRichRuns(runs, atlas, fontFamily, richOpts, style));
+ } else {
+ const plainLines = wrap
+ ? rawLines.flatMap(l => wrapLine(l, atlas, fontFamily, opts.fontSizePx, style, opts.maxWidth!, opts.letterSpacing ?? 0))
+ : rawLines;
+ const kept = plainLines.slice(0, maxLines === Infinity ? undefined : maxLines);
+ const dropped = kept.length < plainLines.length;
+ const measure = (t: string) => measureWidth(t, atlas, fontFamily, opts.fontSizePx, style, opts.letterSpacing ?? 0);
+ const cut = kept.map((line, i) => {
+ const last = i === kept.length - 1;
+ // The last kept line carries the ellipsis when lines were dropped, even
+ // if it fits: the mark says "there is more", not "this line was long".
+ if (dropped && last && ellipsis) return truncateLine(line + ELLIPSIS, measure, widthLimit || Infinity, true);
+ return widthLimit > 0 ? truncateLine(line, measure, widthLimit, ellipsis) : line;
+ });
+ lineLayouts = cut.map(line => layoutLine(line, atlas, fontFamily, opts, style));
+ }
const lines = lineLayouts; // line count only below
const contentWidth = lineLayouts.reduce((m, l) => Math.max(m, l.width), 0);
diff --git a/sdk/src/ui/text/plugin.ts b/sdk/src/ui/text/plugin.ts
index 4360924d0..057f07256 100644
--- a/sdk/src/ui/text/plugin.ts
+++ b/sdk/src/ui/text/plugin.ts
@@ -215,6 +215,7 @@ export class TextPlugin implements Plugin {
maxWidth,
boxWidth,
boxHeight,
+ overflow: t.overflow,
originX,
originY,
shadow,
diff --git a/sdk/src/ui/text/text-renderer.ts b/sdk/src/ui/text/text-renderer.ts
index 21dfeb5a9..b0f7222c9 100644
--- a/sdk/src/ui/text/text-renderer.ts
+++ b/sdk/src/ui/text/text-renderer.ts
@@ -46,6 +46,8 @@ export interface DrawTextParams {
verticalAlign?: number;
/** Box height (px) for vertical alignment; 0/undefined = boxless (anchor to origin). */
boxHeight?: number;
+ /** What a run too big for the box does: 0 visible | 1 clip | 2 ellipsis. */
+ overflow?: number;
/**
* Drop shadow: an offset, recolored copy of the glyphs drawn behind the fill.
* `blur` (px, 0 = hard) spreads that copy into a ring so the shadow reads as
@@ -177,6 +179,8 @@ export function drawTextWith(atlas: GlyphAtlas, sink: GlyphBatchSink, p: DrawTex
color: p.color,
maxWidth: p.maxWidth,
boxWidth: p.boxWidth,
+ boxHeight: p.boxHeight,
+ overflow: p.overflow,
}, p.style ?? 0);
if (layout.glyphs.length === 0) return;
diff --git a/sdk/tests/ui-text-overflow.test.ts b/sdk/tests/ui-text-overflow.test.ts
new file mode 100644
index 000000000..168b5d851
--- /dev/null
+++ b/sdk/tests/ui-text-overflow.test.ts
@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file ui-text-overflow.test.ts — what Clip and Ellipsis promise.
+ *
+ * Two of these decide whether a reader can tell "this line was long" from "there
+ * is more below": the mark goes on the last kept line whenever lines were
+ * dropped, and a box too short for one line still shows one.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+ GlyphAtlas, type GlyphRasterizer, type AtlasPageStore, type RasterGlyph,
+} from '../src/ui/text/glyph-atlas';
+import {
+ layoutText, measureWidth,
+ TEXT_OVERFLOW_VISIBLE, TEXT_OVERFLOW_CLIP, TEXT_OVERFLOW_ELLIPSIS,
+} from '../src/ui/text/layout';
+
+function makeAtlas(): GlyphAtlas {
+ const rasterizer: GlyphRasterizer = {
+ renderSize: 48,
+ spread: 6,
+ rasterize: (cp: number): RasterGlyph => {
+ // A real font does not advance an ellipsis like a letter, and a fake
+ // that does makes the two modes indistinguishable by width — which is
+ // the only thing a layout hands back.
+ if (cp === 32) return { pixels: new Uint8Array(0), width: 0, height: 0, advance: 6, bearingX: 0, bearingY: 0 };
+ const advance = cp === 0x2026 ? 18 : 11;
+ return { pixels: new Uint8Array(10 * 12 * 4), width: 10, height: 12, advance, bearingX: 1, bearingY: 10 };
+ },
+ };
+ let next = 1;
+ const store: AtlasPageStore = { createPage: () => next++, uploadSubRegion: () => {} };
+ return new GlyphAtlas(rasterizer, store, { pageSize: 256, padding: 1 });
+}
+
+// scale 0.5 at this size: every letter advances 5.5px, a space 3px.
+const F = 24;
+const LINE = F * 1.2;
+const atlas = makeAtlas();
+const width = (s: string) => measureWidth(s, atlas, 'Arial', F, 0);
+
+/** Lines a layout produced, read back off the glyphs' rows. */
+function linesOf(layout: { glyphs: { y0: number }[] }): number {
+ return new Set(layout.glyphs.map((g) => Math.round(g.y0))).size;
+}
+
+const lay = (text: string, opts: Record<string, unknown>) =>
+ layoutText(text, atlas, 'Arial', { fontSizePx: F, lineHeight: LINE, ...opts } as never);
+
+describe('TextOverflow', () => {
+ it('Visible keeps every line, however short the box', () => {
+ const l = lay('one\ntwo\nthree', { boxHeight: LINE, overflow: TEXT_OVERFLOW_VISIBLE });
+ expect(linesOf(l)).toBe(3);
+ });
+
+ it('an unspecified overflow behaves as Visible', () => {
+ const l = lay('one\ntwo\nthree', { boxHeight: LINE });
+ expect(linesOf(l)).toBe(3);
+ });
+
+ it('Clip keeps only the lines the box has room for', () => {
+ expect(linesOf(lay('one\ntwo\nthree', { boxHeight: LINE * 2, overflow: TEXT_OVERFLOW_CLIP }))).toBe(2);
+ expect(linesOf(lay('one\ntwo\nthree', { boxHeight: LINE * 3, overflow: TEXT_OVERFLOW_CLIP }))).toBe(3);
+ });
+
+ it('a box too short for one line still shows one', () => {
+ // Nothing is not an answer a reader can act on, and it is what a rounding
+ // error in the box height would otherwise produce.
+ expect(linesOf(lay('one\ntwo', { boxHeight: 1, overflow: TEXT_OVERFLOW_CLIP }))).toBe(1);
+ });
+
+ it('no box height means nothing can overflow one', () => {
+ expect(linesOf(lay('one\ntwo\nthree', { overflow: TEXT_OVERFLOW_CLIP }))).toBe(3);
+ });
+
+ it('Ellipsis says there is more below, even when the last line fits', () => {
+ // The mark is about the DROPPED lines, not about this line being long —
+ // which is the distinction a reader needs and a width check cannot make.
+ const l = lay('one\ntwo\nthree', { boxHeight: LINE, overflow: TEXT_OVERFLOW_ELLIPSIS, boxWidth: 400 });
+ expect(linesOf(l)).toBe(1);
+ expect(l.width).toBeCloseTo(width('one…'), 5);
+ });
+
+ it('Clip drops the lines and adds no mark', () => {
+ const l = lay('one\ntwo\nthree', { boxHeight: LINE, overflow: TEXT_OVERFLOW_CLIP, boxWidth: 400 });
+ expect(l.width).toBeCloseTo(width('one'), 5);
+ });
+
+ it('a single line too wide for the box is trimmed to fit, ellipsis included', () => {
+ const limit = width('abcde');
+ const l = lay('abcdefghij', { boxWidth: limit, overflow: TEXT_OVERFLOW_ELLIPSIS });
+ expect(l.width).toBeLessThanOrEqual(limit + 1e-6);
+ // Trimmed one glyph at a time, so the result is the widest that FITS —
+ // a proportional guess would leave visible slack or overshoot.
+ expect(l.width).toBeGreaterThan(limit - width('a') - width('…'));
+ });
+
+ it('Clip trims the same line without a mark, and keeps more of it', () => {
+ const limit = width('abcde');
+ const clipped = lay('abcdefghij', { boxWidth: limit, overflow: TEXT_OVERFLOW_CLIP });
+ const ellipsed = lay('abcdefghij', { boxWidth: limit, overflow: TEXT_OVERFLOW_ELLIPSIS });
+ expect(clipped.width).toBeLessThanOrEqual(limit + 1e-6);
+ expect(clipped.width).toBeGreaterThan(ellipsed.width);
+ });
+
+ it('a line that fits is left exactly alone', () => {
+ const l = lay('abc', { boxWidth: width('abcdefgh'), overflow: TEXT_OVERFLOW_ELLIPSIS });
+ expect(l.width).toBeCloseTo(width('abc'), 5);
+ });
+
+ it('wrapping still happens first, and the box then decides how many survive', () => {
+ // maxWidth wraps 'aa aa aa' into three lines; a two-line box keeps two.
+ const l = lay('aa aa aa', {
+ maxWidth: width('aa') + 1, boxHeight: LINE * 2, overflow: TEXT_OVERFLOW_CLIP,
+ });
+ expect(linesOf(l)).toBe(2);
+ });
+
+ it('rich text truncates by line, since a run carries its own size', () => {
+ const l = lay('one\n<b>two</b>\nthree', {
+ rich: true, boxHeight: LINE * 2, overflow: TEXT_OVERFLOW_CLIP,
+ });
+ expect(linesOf(l)).toBe(2);
+ });
+});
diff --git a/tools/check-freeze-bar.mjs b/tools/check-freeze-bar.mjs
index bbf090739..5270199da 100644
--- a/tools/check-freeze-bar.mjs
+++ b/tools/check-freeze-bar.mjs
@@ -81,10 +81,6 @@ export const BLOCKED = {
Not: { needs: 'called by no golden project', why: 'as And' },
addSystem: { needs: 'called by no golden project', why: 'the schedule-less spelling; every project writes addSystemToSchedule instead' },
loadInputMapAsset: { needs: 'called by no golden project', why: 'nothing we certify loads an input map from an asset' },
- // Not a corpus gap: nothing reads TextData.overflow, so Clip and Ellipsis
- // render as Visible. Freezing it would promise a behaviour that is missing,
- // and the Inspector still offers the dropdown — now labelled as such.
- TextOverflow: { needs: 'named by no SDK test', why: 'no layout or render path honours it, so there is no behaviour to pin' },
};
// Scene, Prefab and Assets are NOT here, and the gate is why: each PASSES the bar,
// so what holds them at @beta is a judgement it cannot make — thin evidence for the
diff --git a/tools/check-tier-leaks.mjs b/tools/check-tier-leaks.mjs
index ed824dfcd..6e0867541 100644
--- a/tools/check-tier-leaks.mjs
+++ b/tools/check-tier-leaks.mjs
@@ -28,9 +28,7 @@ import { parseSnapshot } from './lib/apiSnapshot.mjs';
* is the goal state: the whole ECS vocabulary went through the bar, World
* included. A line here is a promise with a declared hole in it.
*/
-export const ACCEPTED = {
- TextData: 'names TextOverflow, unfrozen because no layout or render path reads the field it types',
-};
+export const ACCEPTED = {};
/** Every symbol across every entry, keeping the strongest tier any entry gives it. */
function surface() {
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index 4f68c2d17..c648b84ab 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -79,6 +79,10 @@ export const SCENES = [
// exactly one sits in a stroke wide enough to be flat either side of it, and
// the rest of the frame is the background this distinguishes it from.
{ id: "text", tier: "nightly", env: { ESTELLA_VERIFY_SCENE: "/scenes/ui-text-sdf.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/ui-text-sdf.textures.json", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.42,\"y\":0.42,\"rgb\":[255,255,255],\"tol\":30},{\"x\":0.9,\"y\":0.9,\"rgb\":[0,0,0],\"tol\":20}]" } },
+ // Two identical labels in one-line boxes, Visible beside Clip. The differential
+ // is the point: a truncation that does nothing leaves BOTH second lines drawn,
+ // which one label alone could not say. Probes measured, not guessed.
+ { id: "text-overflow", tier: "nightly", env: { ESTELLA_VERIFY_SCENE: "/scenes/ui-text-overflow.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/ui-text-sdf.textures.json", ESTELLA_VERIFY_W: "800", ESTELLA_VERIFY_H: "600", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.051,\"y\":0.167,\"rgb\":[255,255,255],\"tol\":30},{\"x\":0.051,\"y\":0.35,\"rgb\":[255,255,255],\"tol\":30},{\"x\":0.551,\"y\":0.167,\"rgb\":[255,255,255],\"tol\":30},{\"x\":0.551,\"y\":0.35,\"rgb\":[0,0,0],\"tol\":20}]" } },
{ id: "text-rect", tier: "nightly", rendersOnly: "measured: its glyphs are thinner than any neighbourhood a probe can safely sit in — zero flat interior points", env: { ESTELLA_VERIFY_SCENE: "/scenes/ui-text-rect.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/ui-text-sdf.textures.json" } },
// One point inside each box the flex tree lays out, taken from the middle of
// its flat interior — so a layout that moves a box fails rather than a frame