@roku-sdk/text-layout 0.0.0-stage → 2.19.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roku, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+# @roku-sdk/text-layout
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A pure TypeScript port of the Roku firmware label layout: line breaking, word wrapping and ellipsis placement. It has no dependencies and does no font work itself. You supply a width function, and the package decides where lines break and where text is truncated.
+
+## Width injection
+
+Layout never measures glyphs. `LabelMetrics.width` returns the rendered width of a string in device pixels, and `lineHeight` and `defaultLineSpacing` come from the font and theme. The lower-level functions take a `WidthFn` over UTF-8 bytes. Any measurer works, a font engine or a lookup table.
+
+## Example
+
+```ts
+import { layoutLabel, scalesFor } from "@roku-sdk/text-layout";
+
+// Synthetic measurer: every UTF-8 byte is 10 px wide.
+const metrics = {
+    width: (text: string) => new TextEncoder().encode(text).length * 10,
+    lineHeight: 30,
+    defaultLineSpacing: 12
+};
+
+const layout = layoutLabel(
+    { text: "The quick brown fox jumps over the lazy dog", width: 200, wrap: true, maxLines: 2 },
+    metrics,
+    scalesFor("fhd", "fhd")
+);
+console.log(layout.lines, layout.isTextEllipsized);
+```
+
+## UTF-8
+
+UTF-8 encoding and decoding live in `src/utf8.ts`, the only file that uses `TextEncoder` and `TextDecoder`.

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@roku-sdk/text-layout",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "2.19.1",
+  "description": "Pure TypeScript port of the Roku firmware label line-breaking, wrapping and ellipsis rules, driven by an injected width function",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "engines": {
+    "npm": ">=8.5.0",
+    "node": ">=24.0.0"
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.4.1",
+    "jest": "^30.4.1",
+    "typescript": "^5.9.3",
+    "@roku-sdk/dev-tools": "2.19.1"
+  },
+  "author": "Roku Inc",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/rokudev/rsg-sdk.git",
+    "directory": "packages/text-layout"
+  },
+  "homepage": "https://gitlab.com/rokudev/rsg-sdk/-/tree/main/packages/text-layout#readme",
+  "bugs": {
+    "url": "https://gitlab.com/rokudev/rsg-sdk/-/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "jest --passWithNoTests",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "lint": "eslint --no-error-on-unmatched-pattern \"src/**/*.{ts,tsx,mjs,cjs,js}\""
+  }
 }

package/src/__tests__/api-surface.test.ts

@@ -0,0 +1,29 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { expect, test } from "@jest/globals";
+
+import * as api from "../index";
+
+const NAMES = [
+    "decodeUtf8",
+    "defaultLineSpacing",
+    "drawnLines",
+    "ellipsizeText",
+    "encodeUtf8",
+    "findCharBoundary",
+    "findDelimiterBreak",
+    "findWordBreak",
+    "isWordBreak",
+    "layoutLabel",
+    "layoutLabelInFont",
+    "lineHeightFromExtents",
+    "normalizeWrapText",
+    "scalesFor",
+    "wrapText"
+];
+
+test("root export is exactly the public layout surface", () => {
+    expect(Object.keys(api).sort()).toEqual(NAMES);
+    for (const name of NAMES) expect(typeof (api as Record<string, unknown>)[name]).toBe("function");
+});

package/src/__tests__/label-layout.test.ts

@@ -0,0 +1,306 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+//
+// Pure unit tests for the label layout port. Widths come from a SYNTHETIC measurer (10 px per UTF-8 byte), so
+// the tests pin the firmware's line-breaking and ellipsis rules without fonts.
+
+import { describe, expect, test } from "@jest/globals";
+
+import {
+    defaultLineSpacing,
+    drawnLines,
+    encodeUtf8,
+    findDelimiterBreak,
+    type LabelProps,
+    layoutLabel,
+    layoutLabelInFont,
+    lineHeightFromExtents,
+    scalesFor
+} from "../index";
+
+const metrics = {
+    width: (text: string): number => new TextEncoder().encode(text).length * 10,
+    lineHeight: 26,
+    defaultLineSpacing: 8
+};
+
+function layout(props: LabelProps, scales = scalesFor("hd", "hd")) {
+    return layoutLabel(props, metrics, scales);
+}
+
+describe("line breaking", () => {
+    test("a candidate fits when its whole substring is <= the width", () => {
+        expect(layout({ text: "aaa bbb ccc", width: 70 }).lines).toEqual(["aaa bbb", "ccc"]);
+        expect(layout({ text: "aaa bbb ccc", width: 69 }).lines).toEqual(["aaa", "bbb", "ccc"]);
+    });
+
+    test("every space is a break candidate; spaces before the break stay on the line and are measured", () => {
+        expect(layout({ text: "aa   bb", width: 40 }).lines).toEqual(["aa  ", "bb"]);
+        expect(layout({ text: "aa   bb", width: 39 }).lines).toEqual(["aa ", "bb"]);
+    });
+
+    test("a hyphen stays on the first line", () => {
+        expect(layout({ text: "well-known fox", width: 60 }).lines).toEqual(["well-", "known", "fox"]);
+    });
+
+    test("trailing whitespace is dropped, CR LF becomes LF, a tab becomes four spaces", () => {
+        expect(layout({ text: "a\r\nb\tc   ", width: 400 }).lines).toEqual(["a", "b    c"]);
+    });
+
+    test("leading spaces after a newline are kept; blank lines count", () => {
+        expect(layout({ text: "a\n  b", width: 400 }).lines).toEqual(["a", "  b"]);
+        expect(layout({ text: "a\n\nb", width: 400 }).numLines).toBe(3);
+    });
+
+    test("a word wider than the box is split by characters", () => {
+        expect(layout({ text: "abcdefgh", width: 30 }).lines).toEqual(["abc", "def", "gh"]);
+    });
+
+    test("the character search assumes the whole remainder minus one byte does not fit", () => {
+        // One glyph per line: the last line is lost to the empty "cannot display one character" line.
+        expect(layout({ text: "abc", width: 10 }).lines).toEqual(["a", ""]);
+        expect(layout({ text: "abcd", width: 19 }).lines).toEqual(["a", "b", ""]);
+    });
+
+    test("a box narrower than one glyph yields a single empty line", () => {
+        expect(layout({ text: "abc", width: 5 }).lines).toEqual([""]);
+        expect(layout({ text: "ab", width: 5 }).lines).toEqual([""]);
+    });
+
+    test("the character search works on UTF-8 bytes and never splits a character", () => {
+        expect(layout({ text: "ééé", width: 25 }).lines).toEqual(["é", "é", "é"]);
+        // The last character is two bytes, so the "all but the last byte" bound does not cost a line.
+        expect(layout({ text: "éé", width: 20 }).lines).toEqual(["é", "é"]);
+    });
+
+    test("wordBreakChars add break characters that stay on the first line", () => {
+        expect(layout({ text: "aa/bb/cc", width: 50, wordBreakChars: "/" }).lines).toEqual(["aa/", "bb/cc"]);
+        expect(layout({ text: "aa/bb/cc", width: 50 }).lines).toEqual(["aa/bb", "/cc"]);
+    });
+});
+
+describe("ellipsis", () => {
+    test("a single line is clipped so that width(clip) + width(ellipsis) <= width", () => {
+        const r = layout({ text: "abcdefghij", width: 65, wrap: false });
+        expect(r.lines).toEqual(["abc..."]);
+        expect(r.isTextEllipsized).toBe(true);
+        expect(r.numLines).toBeNull();
+    });
+
+    test("an ellipsis wider than the box returns an empty string and is not flagged", () => {
+        const r = layout({ text: "abcdefghij", width: 20, wrap: false });
+        expect(r.lines).toEqual([""]);
+        expect(r.isTextEllipsized).toBe(false);
+    });
+
+    test("text that fits is untouched; a single line stops at the first newline", () => {
+        expect(layout({ text: "abc", width: 30, wrap: false }).isTextEllipsized).toBe(false);
+        expect(layout({ text: "abc\ndef", width: 30, wrap: false })).toMatchObject({
+            lines: ["abc"],
+            isTextEllipsized: false
+        });
+    });
+
+    test("maxLines ellipsizes the last allowed line from the remaining text", () => {
+        expect(layout({ text: "aaa bbb ccc ddd", width: 40, maxLines: 2 })).toMatchObject({
+            numLines: 2,
+            isTextEllipsized: true,
+            lines: ["aaa", "b..."]
+        });
+        expect(layout({ text: "aaa", width: 40, maxLines: 1 })).toMatchObject({ numLines: 1, isTextEllipsized: false });
+        expect(layout({ text: "aaa bbb", width: 40, maxLines: 5 })).toMatchObject({
+            numLines: 2,
+            isTextEllipsized: false
+        });
+    });
+
+    test("options: custom ellipsis, ellipsizeOnBoundary, leadingEllipsis, truncateOnDelimiter", () => {
+        expect(layout({ text: "abcdefghij", width: 60, wrap: false, ellipsisText: "~" }).lines).toEqual(["abcde~"]);
+        expect(layout({ text: "abc defg hij", width: 100, wrap: false, ellipsizeOnBoundary: true }).lines).toEqual([
+            "abc ..."
+        ]);
+        expect(layout({ text: "abcdefghij", width: 65, wrap: false, leadingEllipsis: true }).lines).toEqual(["...hij"]);
+        expect(layout({ text: "ab cd ef gh", width: 60, wrap: false, truncateOnDelimiter: " " }).lines).toEqual([
+            "ab cd"
+        ]);
+    });
+});
+
+describe("degenerate input", () => {
+    test("empty, blank and whitespace-only text is one empty-looking line", () => {
+        expect(layout({ text: "", width: 100 })).toMatchObject({ numLines: 1, lines: [""], isTextEllipsized: false });
+        expect(layout({ text: "     ", width: 100 }).numLines).toBe(1);
+        expect(layout({ text: "\n", width: 100 }).numLines).toBe(1);
+    });
+
+    test("a lone carriage return is a line break", () => {
+        expect(layout({ text: "a\rb", width: 100 }).lines).toEqual(["a", "b"]);
+    });
+
+    test("width 0 with wrap draws nothing: wrapText returns without producing a line", () => {
+        expect(layout({ text: "abc def\nghi", width: 0 })).toMatchObject({
+            numLines: null,
+            lines: [],
+            isTextEllipsized: false
+        });
+    });
+
+    test("width 0 without wrap is an auto-width single line: the first line whole, never ellipsized", () => {
+        expect(layout({ text: "abc def\nghi", width: 0, wrap: false })).toMatchObject({
+            numLines: null,
+            lines: ["abc def"],
+            isTextEllipsized: false
+        });
+    });
+
+    test("a box narrower than one pixel still reports one line", () => {
+        expect(layout({ text: "abc def", width: 0.5 }).numLines).toBe(1);
+    });
+
+    test("a long text finishes quickly", () => {
+        const words = Array.from({ length: 3000 }, (_, i) => `word${i}`).join(" ");
+        const started = Date.now();
+        expect(layout({ text: words, width: 300 }).numLines).toBeGreaterThan(900);
+        expect(Date.now() - started).toBeLessThan(3000);
+    });
+});
+
+describe("height", () => {
+    test("an explicit height allows floor((height + spacing) / (lineHeight + spacing)) lines, the last ellipsized", () => {
+        expect(layout({ text: "aaa bbb ccc ddd eee", width: 40, height: 70 })).toMatchObject({
+            numLines: 2,
+            isTextEllipsized: true,
+            lines: ["aaa", "b..."]
+        });
+        expect(layout({ text: "aaa bbb ccc ddd", width: 40, height: 52, lineSpacing: 0 }).numLines).toBe(2);
+    });
+
+    test("a height smaller than one line still reports one ellipsized line", () => {
+        expect(layout({ text: "aaa bbb ccc", width: 40, height: 25 })).toMatchObject({
+            numLines: 1,
+            isTextEllipsized: true,
+            lines: ["a..."]
+        });
+    });
+
+    test("numLines sets the height; auto height follows the wrapped lines", () => {
+        expect(layout({ text: "aaa bbb ccc ddd", width: 40, numLines: 2 })).toMatchObject({
+            numLines: 2,
+            isTextEllipsized: true,
+            height: 60
+        });
+        expect(layout({ text: "aaa bbb ccc", width: 40 }).height).toBe(94);
+    });
+
+    test("maxLines clamps the height to a whole number, as the firmware's int maxHeight does", () => {
+        // 2 * 26 + 1 * 6.5 = 58.5 is truncated to 58, so even the first line no longer fits above 58.5.
+        expect(layout({ text: "aaa bbb ccc ddd", width: 40, maxLines: 2, lineSpacing: 6.5 })).toMatchObject({
+            numLines: 1,
+            isTextEllipsized: true,
+            lines: ["a..."],
+            height: 58
+        });
+    });
+
+    test("displayPartialLines wraps the whole text and never ellipsizes", () => {
+        expect(layout({ text: "aaa bbb ccc ddd", width: 40, displayPartialLines: true })).toMatchObject({
+            numLines: 4,
+            isTextEllipsized: false
+        });
+        expect(layout({ text: "aaa bbb ccc ddd", width: 40, displayPartialLines: true, height: 60 })).toMatchObject({
+            numLines: 2,
+            isTextEllipsized: false
+        });
+    });
+});
+
+describe("drawn lines", () => {
+    test("every computed line is drawn when the label is as tall as its lines", () => {
+        const props = { text: "aaa bbb ccc", width: 40 };
+        expect(drawnLines(layout(props), props)).toEqual(["aaa", "bbb", "ccc"]);
+    });
+
+    test("a line that does not fit the height is not drawn; a height below one line draws nothing", () => {
+        const props = { text: "aaa bbb ccc ddd eee", width: 40, height: 70 };
+        expect(drawnLines(layout(props), props)).toEqual(["aaa", "b..."]);
+        const tiny = { text: "aaa bbb ccc", width: 40, height: 25 };
+        expect(drawnLines(layout(tiny), tiny)).toEqual([]);
+    });
+
+    test("displayPartialLines draws nothing without an explicit height", () => {
+        const noHeight = { text: "aaa bbb ccc ddd", width: 40, displayPartialLines: true };
+        expect(drawnLines(layout(noHeight), noHeight)).toEqual([]);
+        const withHeight = { ...noHeight, height: 60 };
+        expect(drawnLines(layout(withHeight), withHeight)).toEqual(["aaa", "bbb"]);
+    });
+
+    test("a single line is always drawn", () => {
+        const props = { text: "abcdefghij", width: 65, wrap: false };
+        expect(drawnLines(layout(props), props)).toEqual(["abc..."]);
+    });
+});
+
+describe("resolutions", () => {
+    test("the scale factors are float32 and swap with the app/device pair", () => {
+        expect(scalesFor("hd", "hd")).toEqual({ autoScale: 1, autoScaleInv: 1 });
+        expect(scalesFor("hd", "fhd")).toEqual({ autoScale: 1.5, autoScaleInv: Math.fround(2 / 3) });
+        expect(scalesFor("fhd", "hd")).toEqual({ autoScale: Math.fround(2 / 3), autoScaleInv: 1.5 });
+    });
+
+    test("wrapping compares device pixels with the box width scaled to device pixels", () => {
+        // hd app on a 1080p device: width 47 is 70.5 device px, so a 70 px line fits.
+        expect(layout({ text: "aaa bbb ccc", width: 47 }, scalesFor("hd", "fhd")).lines).toEqual(["aaa bbb", "ccc"]);
+        expect(layout({ text: "aaa bbb ccc", width: 46 }, scalesFor("hd", "fhd")).lines).toEqual(["aaa", "bbb", "ccc"]);
+        // fhd app on a 720p device: width 105 is 70 device px.
+        expect(layout({ text: "aaa bbb ccc", width: 105 }, scalesFor("fhd", "hd")).lines).toEqual(["aaa bbb", "ccc"]);
+        expect(layout({ text: "aaa bbb ccc", width: 104 }, scalesFor("fhd", "hd")).lines).toEqual([
+            "aaa",
+            "bbb",
+            "ccc"
+        ]);
+    });
+
+    test("default line spacing follows the app resolution; line height comes from the font extents", () => {
+        expect(defaultLineSpacing("hd")).toBe(8);
+        expect(defaultLineSpacing("fhd")).toBe(12);
+        expect(lineHeightFromExtents(19.203, 4.797)).toBe(26);
+        expect(lineHeightFromExtents(24, 6)).toBe(31);
+    });
+});
+
+describe("byte semantics", () => {
+    test("findDelimiterBreak searches bytes, not characters", () => {
+        const text = encodeUtf8("★☆ Yo chann");
+        const cfg = {
+            wordBreakChars: new Uint8Array(),
+            ellipsisText: encodeUtf8("..."),
+            ellipsizeOnBoundary: false,
+            truncateOnDelimiter: encodeUtf8(" "),
+            leadingEllipsis: false
+        };
+        // "★☆" is six bytes, so the first space is at byte 6, not character 2.
+        expect(findDelimiterBreak(text, 0, 3, text.length - 1, cfg)).toBe(6);
+    });
+
+    test("a probe cut inside a character measures without the partial character", () => {
+        // The first break sets the line-length hint to 4, so the second paragraph is probed at byte 24, which is
+        // the lead byte of "é". The device fits it; a stray replacement character would make the probe too wide.
+        const metrics = {
+            width: (text: string) => [...text].reduce((sum, ch) => sum + (ch === "\uFFFD" ? 200 : 10), 0),
+            lineHeight: 20,
+            defaultLineSpacing: 0
+        };
+        const second = `${"b".repeat(23)}é${"c".repeat(10)}`;
+        const result = layoutLabel({ text: `aaaa ${second}\nz`, width: 360 }, metrics, scalesFor("fhd", "fhd"));
+        expect(result.lines).toEqual(["aaaa", second, "z"]);
+    });
+});
+
+describe("layoutLabelInFont", () => {
+    test("derives line height from extents and shapes at the given resolutions", () => {
+        const font = { width: (t: string) => t.length * 10, ascender: 10, descender: 3 };
+        const result = layoutLabelInFont({ text: "abcd efgh ijkl", width: 90 }, font, "fhd", "fhd");
+        expect(result.lines).toEqual(["abcd efgh", "ijkl"]);
+        expect(result.lineHeight).toBe(14);
+    });
+});

package/src/__tests__/utf8-isolation.test.ts

@@ -0,0 +1,23 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { expect, test } from "@jest/globals";
+
+const srcDir = join(__dirname, "..");
+
+function sourceFiles(dir: string): string[] {
+    return readdirSync(dir, { withFileTypes: true }).flatMap(entry => {
+        if (entry.isDirectory()) return entry.name === "__tests__" ? [] : sourceFiles(join(dir, entry.name));
+        return entry.name.endsWith(".ts") && !entry.name.endsWith(".test.ts") ? [join(dir, entry.name)] : [];
+    });
+}
+
+test("only utf8.ts touches TextEncoder or TextDecoder", () => {
+    const users = sourceFiles(srcDir)
+        .filter(file => /TextEncoder|TextDecoder/.test(readFileSync(file, "utf8")))
+        .map(file => file.slice(srcDir.length + 1));
+    expect(users).toEqual(["utf8.ts"]);
+});

package/src/break-search.ts

@@ -0,0 +1,56 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { at, findBytes, isSpace, reverseFindBytes } from "./bytes";
+import type { BreakConfig } from "./types";
+
+const HYPHEN = 45;
+
+/** `LabelBase::isWordBreak`: whitespace, `-`, or any byte of `wordBreakChars`. */
+export const isWordBreak = (c: number, cfg: BreakConfig): boolean =>
+    isSpace(c) || c === HYPHEN || cfg.wordBreakChars.includes(c);
+
+/**
+ * `LabelBase::findWordBreak`. Returns a break position between `min` and `max` closest to `pos`
+ * (forward first, then backward), or -1. A non-space break character stays on the first line, so the
+ * position is one past it. May return `max + 1`: the firmware does not guard that case.
+ */
+export function findWordBreak(text: Uint8Array, min: number, pos: number, max: number, cfg: BreakConfig): number {
+    const startPos = pos;
+
+    while (!isWordBreak(at(text, pos), cfg) && pos < max) pos++;
+    if (isWordBreak(at(text, pos), cfg) && !isSpace(at(text, pos))) pos++;
+
+    if (pos === max) {
+        pos = startPos - 1;
+        if (pos < min) pos = min;
+        while (pos > min && !isWordBreak(at(text, pos), cfg)) pos--;
+        if (isWordBreak(at(text, pos), cfg) && !isSpace(at(text, pos))) pos++;
+        if (pos === min) return -1;
+    }
+    return pos;
+}
+
+/** `LabelBase::findCharBoundary`: a UTF-8 character boundary near `mid`, or -1. */
+export function findCharBoundary(text: Uint8Array, min: number, mid: number, max: number): number {
+    while ((at(text, mid) & 0xc0) === 0x80 && mid !== min) mid--;
+
+    if (min === mid) {
+        mid = 1 + ((max + min) >> 1);
+        while (mid !== max && (at(text, mid) & 0xc0) === 0x80) mid++;
+        if (mid === max) return -1;
+    }
+    return mid;
+}
+
+/** `LabelBase::findDelimiterBreak`: byte search for the `truncateOnDelimiter` string, or -1. */
+export function findDelimiterBreak(text: Uint8Array, min: number, pos: number, max: number, cfg: BreakConfig): number {
+    const startPos = pos;
+    let found = findBytes(text, cfg.truncateOnDelimiter, pos);
+
+    if (found < 0 || found >= max) {
+        found = reverseFindBytes(text, cfg.truncateOnDelimiter, startPos - 1);
+        if (found < 0 || found <= min) return -1;
+    }
+    return found;
+}

package/src/bytes.ts

@@ -0,0 +1,98 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+// UTF-8 byte helpers mirroring the C locale `isspace` and the `std::string` operations the firmware label code uses.
+
+/**
+ * Drops a UTF-8 sequence that the end of `bytes` cuts short. The device measures a string cut inside a character
+ * without that character; decoding it as-is would add a replacement glyph, which is far wider.
+ */
+export function withoutPartialTail(bytes: Uint8Array): Uint8Array {
+    let start = bytes.length;
+    // Walk back over at most three continuation bytes to the lead byte of the final character.
+    while (start > 0 && bytes.length - start < 3 && (bytes[start - 1] & 0xc0) === 0x80) start--;
+    if (start === 0) return bytes;
+    const lead = bytes[start - 1];
+    const expected = lead >= 0xf0 ? 4 : lead >= 0xe0 ? 3 : lead >= 0xc0 ? 2 : 1;
+    return bytes.length - (start - 1) < expected ? bytes.slice(0, start - 1) : bytes;
+}
+
+const NEWLINE = 10;
+const CARRIAGE_RETURN = 13;
+const SPACE = 32;
+const TAB = 9;
+
+/** C locale isspace: space, \t, \n, \v, \f, \r. */
+export const isSpace = (c: number): boolean => c === SPACE || (c >= TAB && c <= CARRIAGE_RETURN);
+
+/** Space that is not a line terminator. */
+export const isSpaceNotNewline = (c: number): boolean => isSpace(c) && c !== CARRIAGE_RETURN && c !== NEWLINE;
+
+/** `std::string::at`: throws where the firmware throws `std::out_of_range`. */
+export function at(bytes: Uint8Array, index: number): number {
+    if (index < 0 || index >= bytes.length) throw new RangeError(`out_of_range: ${index} of ${bytes.length}`);
+    return bytes[index];
+}
+
+export function concat(a: Uint8Array, b: Uint8Array): Uint8Array {
+    const out = new Uint8Array(a.length + b.length);
+    out.set(a);
+    out.set(b, a.length);
+    return out;
+}
+
+export function trimTrailingWhitespace(bytes: Uint8Array): Uint8Array {
+    let end = bytes.length;
+    while (end > 0 && isSpace(bytes[end - 1])) end--;
+    return bytes.slice(0, end);
+}
+
+export function trimLeadingWhitespace(bytes: Uint8Array): Uint8Array {
+    let start = 0;
+    while (start < bytes.length && isSpace(bytes[start])) start++;
+    return bytes.slice(start);
+}
+
+/** `find_first_of("\r\n")`, or -1. */
+export function firstLineBreak(bytes: Uint8Array): number {
+    for (let i = 0; i < bytes.length; i++) if (bytes[i] === CARRIAGE_RETURN || bytes[i] === NEWLINE) return i;
+    return -1;
+}
+
+/** `std::string::find(needle, from)`, or -1. */
+export function findBytes(haystack: Uint8Array, needle: Uint8Array, from: number): number {
+    for (let i = Math.max(0, from); i + needle.length <= haystack.length; i++) {
+        if (matchesAt(haystack, needle, i)) return i;
+    }
+    return -1;
+}
+
+/** `std::string::rfind(needle, from)`; a negative `from` behaves as `npos` (search from the end), or -1. */
+export function reverseFindBytes(haystack: Uint8Array, needle: Uint8Array, from: number): number {
+    const last = haystack.length - needle.length;
+    for (let i = from < 0 ? last : Math.min(from, last); i >= 0; i--) {
+        if (matchesAt(haystack, needle, i)) return i;
+    }
+    return -1;
+}
+
+function matchesAt(haystack: Uint8Array, needle: Uint8Array, at: number): boolean {
+    for (let j = 0; j < needle.length; j++) if (haystack[at + j] !== needle[j]) return false;
+    return true;
+}
+
+/**
+ * The firmware's wrap preprocessing: trailing whitespace of the whole text is dropped,
+ * CR LF becomes LF, and every tab becomes four spaces. Inner spaces are not collapsed.
+ */
+export function normalizeWrapText(text: Uint8Array): Uint8Array {
+    const trimmed = trimTrailingWhitespace(text);
+    const out: number[] = [];
+    for (let i = 0; i < trimmed.length; i++) {
+        const c = trimmed[i];
+        if (c === CARRIAGE_RETURN && trimmed[i + 1] === NEWLINE) continue;
+        if (c === TAB) out.push(SPACE, SPACE, SPACE, SPACE);
+        else out.push(c);
+    }
+    return Uint8Array.from(out);
+}

package/src/ellipsize.ts

@@ -0,0 +1,67 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { findCharBoundary, findDelimiterBreak, findWordBreak } from "./break-search";
+import { concat, firstLineBreak, trimLeadingWhitespace, trimTrailingWhitespace } from "./bytes";
+import type { BreakConfig, LayoutEnv } from "./types";
+
+const fround = Math.fround;
+
+export interface EllipsizeResult {
+    text: Uint8Array;
+    ellipsized: boolean;
+}
+
+/**
+ * `LabelBase::ellipsizeText`. `width` is the box width in **app** pixels (a float32 in the firmware);
+ * font widths are device pixels scaled back to app pixels, so the comparison is additive
+ * (`width(clipped) + width(ellipsis) <= width`), with no kerning between the clip and the dots.
+ */
+export function ellipsizeText(input: Uint8Array, width: number, cfg: BreakConfig, env: LayoutEnv): EllipsizeResult {
+    let text: Uint8Array = input.slice();
+    const lineBreak = firstLineBreak(text);
+    if (lineBreak >= 0) text = text.slice(0, lineBreak);
+    if (!cfg.leadingEllipsis) text = trimTrailingWhitespace(text);
+
+    const appWidth = (bytes: Uint8Array): number => fround(env.width(bytes) * env.autoScaleInv);
+
+    if (appWidth(text) <= width) {
+        if (lineBreak < 0) return { text, ellipsized: false };
+        const withEllipsis = concat(text, cfg.ellipsisText);
+        if (appWidth(withEllipsis) <= width) return { text: withEllipsis, ellipsized: true };
+    }
+
+    const truncate = cfg.truncateOnDelimiter.length > 0;
+    const ellipsisWidth = truncate ? 0 : appWidth(cfg.ellipsisText);
+    if (ellipsisWidth > width) return { text: new Uint8Array(), ellipsized: false };
+
+    let max = text.length - 1;
+    let min = 0;
+    while (min + 1 < max) {
+        let mid = (max + min) >> 1;
+        if (truncate) {
+            mid = findDelimiterBreak(text, min, mid, max, cfg);
+            if (mid < 0) break;
+        } else if (cfg.ellipsizeOnBoundary) {
+            mid = findWordBreak(text, min, mid, max, cfg);
+            if (mid < 0) break;
+        } else {
+            mid = findCharBoundary(text, min, mid, max);
+            if (mid < 0) break;
+        }
+
+        const clipped = cfg.leadingEllipsis ? text.slice(mid) : text.slice(0, mid);
+        const fits = fround(appWidth(clipped) + ellipsisWidth) <= width;
+        if (fits) {
+            if (cfg.leadingEllipsis) max = mid;
+            else min = mid;
+        } else if (cfg.leadingEllipsis) min = mid;
+        else max = mid;
+    }
+
+    if (truncate) return { text: text.slice(0, min), ellipsized: true };
+    if (cfg.leadingEllipsis) {
+        return { text: concat(cfg.ellipsisText, trimLeadingWhitespace(text.slice(max))), ellipsized: true };
+    }
+    return { text: concat(trimTrailingWhitespace(text.slice(0, min)), cfg.ellipsisText), ellipsized: true };
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+export { findCharBoundary, findDelimiterBreak, findWordBreak, isWordBreak } from "./break-search";
+export { normalizeWrapText } from "./bytes";
+export { type EllipsizeResult, ellipsizeText } from "./ellipsize";
+export type { BreakConfig, LayoutEnv, WidthFn } from "./types";
+export { type WrapParams, type WrapResult, wrapText } from "./wrap-text";
+export {
+    defaultLineSpacing,
+    drawnLines,
+    type LabelFont,
+    type LabelLayout,
+    type LabelMetrics,
+    type LabelProps,
+    layoutLabel,
+    layoutLabelInFont,
+    lineHeightFromExtents,
+    type ResolutionScales,
+    scalesFor,
+    type UiResolution
+} from "./layout";
+export { decodeUtf8, encodeUtf8 } from "./utf8";

package/src/layout.ts

@@ -0,0 +1,203 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { firstLineBreak, withoutPartialTail } from "./bytes";
+import { ellipsizeText } from "./ellipsize";
+import type { BreakConfig, LayoutEnv } from "./types";
+import { decodeUtf8, encodeUtf8 } from "./utf8";
+import { wrapText } from "./wrap-text";
+
+const fround = Math.fround;
+
+export type UiResolution = "hd" | "fhd";
+
+/** The `Label` properties that affect line breaking and ellipsis. Widths and heights are in app pixels. */
+export interface LabelProps {
+    text: string;
+    width: number;
+    wrap?: boolean;
+    height?: number;
+    numLines?: number;
+    maxLines?: number;
+    lineSpacing?: number;
+    wordBreakChars?: string;
+    ellipsisText?: string;
+    ellipsizeOnBoundary?: boolean;
+    truncateOnDelimiter?: string;
+    displayPartialLines?: boolean;
+    leadingEllipsis?: boolean;
+}
+
+/** Per-font inputs of a layout: widths at the **device** resolution and the line height at the **app** resolution. */
+export interface LabelMetrics {
+    /** `getOneLineWidth` at the device resolution, whole pixels. */
+    width: (text: string) => number;
+    /** `getLineHeight` of the font at the app resolution. */
+    lineHeight: number;
+    /** The theme's `DefaultLabelSpacing` at the app resolution. */
+    defaultLineSpacing: number;
+}
+
+export interface LabelLayout {
+    /** `numWrappedLines`; null when the label does not wrap (a single line is drawn). */
+    numLines: number | null;
+    isTextEllipsized: boolean;
+    /** The lines the firmware computed, ellipsis included. Not all of them are drawn (see `displayPartialLines`). */
+    lines: string[];
+    /** `mHeight` in app pixels. */
+    height: number;
+    lineHeight: number;
+    lineSpacing: number;
+}
+
+export interface ResolutionScales {
+    autoScale: number;
+    autoScaleInv: number;
+}
+
+/** `Scene::resolutionAutoScaleFactor` and its inverse for an app designed for `app` on a device showing `device`. */
+export function scalesFor(app: UiResolution, device: UiResolution): ResolutionScales {
+    if (app === device) return { autoScale: 1, autoScaleInv: 1 };
+    if (app === "hd") return { autoScale: fround(1080 / 720), autoScaleInv: fround(720 / 1080) };
+    return { autoScale: fround(720 / 1080), autoScaleInv: fround(1080 / 720) };
+}
+
+/** `GenevaTheme.xml` `DefaultLabelSpacing`: 8 for hd, 12 for fhd, in app pixels. */
+export const defaultLineSpacing = (app: UiResolution): number => (app === "fhd" ? 12 : 8);
+
+/** The firmware's line height from the font's hhea extents, in pixels: `ceil(ascender) + ceil(descender) + 1`. */
+export const lineHeightFromExtents = (ascender: number, descender: number): number =>
+    Math.ceil(ascender) + Math.ceil(descender) + 1;
+
+const FLOAT_MAX = Number.POSITIVE_INFINITY;
+
+/**
+ * The line-breaking and ellipsis part of `Label::updateTextLayout` / `Label::renderSingle`.
+ * Throws a RangeError where the firmware throws `std::out_of_range`.
+ */
+export function layoutLabel(props: LabelProps, metrics: LabelMetrics, scales: ResolutionScales): LabelLayout {
+    const env: LayoutEnv = {
+        width: bytes => metrics.width(decodeUtf8(withoutPartialTail(bytes))),
+        autoScale: scales.autoScale,
+        autoScaleInv: scales.autoScaleInv
+    };
+    const cfg: BreakConfig = {
+        wordBreakChars: encodeUtf8(props.wordBreakChars ?? ""),
+        ellipsisText: encodeUtf8(props.ellipsisText || (props.ellipsizeOnBoundary ? " ..." : "...")),
+        ellipsizeOnBoundary: !!props.ellipsizeOnBoundary,
+        truncateOnDelimiter: encodeUtf8(props.truncateOnDelimiter ?? ""),
+        leadingEllipsis: !!props.leadingEllipsis
+    };
+    const width = fround(props.width);
+    const lineHeight = metrics.lineHeight;
+    const lineSpacing = props.lineSpacing ?? metrics.defaultLineSpacing;
+    const raw = encodeUtf8(props.text);
+
+    if (props.wrap === false || width <= 0) {
+        let display = raw;
+        const lineBreak = firstLineBreak(display);
+        if (lineBreak >= 0) display = display.slice(0, lineBreak);
+        if (width <= 0) {
+            // An auto-width label (width 0) draws its first line whole and never ellipsizes, but only when it does
+            // not wrap: wrapText returns at once for a width of 0, so a wrapping label has no lines and draws nothing.
+            return {
+                numLines: null,
+                isTextEllipsized: false,
+                lines: props.wrap === false ? [decodeUtf8(display)] : [],
+                height: lineHeight,
+                lineHeight,
+                lineSpacing
+            };
+        }
+        const single = ellipsizeText(display, width, cfg, env);
+        return {
+            numLines: null,
+            isTextEllipsized: single.ellipsized,
+            lines: [decodeUtf8(single.text)],
+            height: lineHeight,
+            lineHeight,
+            lineSpacing
+        };
+    }
+
+    const explicitHeight = (props.height ?? 0) > 0;
+    const numLines = props.numLines ?? 0;
+    const autoHeight = !explicitHeight && numLines <= 0;
+    let height = explicitHeight
+        ? fround(props.height as number)
+        : numLines > 0
+          ? numLines * lineHeight + (numLines - 1) * lineSpacing
+          : FLOAT_MAX;
+
+    const wrapParams = () => ({
+        width,
+        height,
+        lineHeight,
+        lineSpacing,
+        displayPartialLines: !!props.displayPartialLines
+    });
+    let result = wrapText(raw, wrapParams(), cfg, env);
+
+    if (autoHeight) {
+        height = result.lines.length * (lineHeight + lineSpacing) - lineSpacing;
+        const maxLines = props.maxLines ?? 0;
+        if (maxLines > 0) {
+            // `int maxHeight`, with a float spacing term: the sum is truncated toward zero.
+            const maxHeight = Math.trunc(fround(maxLines * lineHeight + fround((maxLines - 1) * lineSpacing)));
+            if (height > maxHeight) {
+                height = maxHeight;
+                result = wrapText(raw, wrapParams(), cfg, env);
+            }
+        }
+    }
+
+    return {
+        numLines: result.lines.length,
+        isTextEllipsized: result.ellipsized,
+        lines: result.lines.map(decodeUtf8),
+        height,
+        lineHeight,
+        lineSpacing
+    };
+}
+
+/** A font as a layout sees it: widths at the device resolution, extents at the app resolution. */
+export interface LabelFont {
+    width: (text: string) => number;
+    ascender: number;
+    descender: number;
+}
+
+export function layoutLabelInFont(
+    props: LabelProps,
+    font: LabelFont,
+    appResolution: UiResolution,
+    deviceResolution: UiResolution
+): LabelLayout {
+    return layoutLabel(
+        props,
+        {
+            width: font.width,
+            lineHeight: lineHeightFromExtents(font.ascender, font.descender),
+            defaultLineSpacing: defaultLineSpacing(appResolution)
+        },
+        scalesFor(appResolution, deviceResolution)
+    );
+}
+
+/**
+ * The lines a wrapping label actually draws. `numWrappedLines` counts every computed line, but a line is drawn only
+ * if it fits the label height (with `displayPartialLines`, if it starts inside it), and `displayPartialLines`
+ * without an explicit height draws nothing at all (observed on the device).
+ */
+export function drawnLines(
+    layout: LabelLayout,
+    props: Pick<LabelProps, "wrap" | "displayPartialLines" | "height">
+): string[] {
+    if (props.wrap === false || layout.numLines === null) return layout.lines;
+    if (props.displayPartialLines && !((props.height ?? 0) > 0)) return [];
+    const pitch = layout.lineHeight + layout.lineSpacing;
+    return layout.lines.filter((_, i) =>
+        props.displayPartialLines ? i * pitch <= layout.height : i * pitch + layout.lineHeight <= layout.height
+    );
+}

package/src/types.ts

@@ -0,0 +1,26 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+/** Width of a UTF-8 byte string in whole device pixels, as `GfxFont::getOneLineWidth` returns it. */
+export type WidthFn = (bytes: Uint8Array) => number;
+
+/** What the break-search code needs from a label's properties. */
+export interface BreakConfig {
+    /** `wordBreakChars` as UTF-8 bytes; the firmware compares single bytes. */
+    wordBreakChars: Uint8Array;
+    /** The resolved ellipsis, already defaulted (`"..."`, or `" ..."` when `ellipsizeOnBoundary`). */
+    ellipsisText: Uint8Array;
+    ellipsizeOnBoundary: boolean;
+    /** Empty when `truncateOnDelimiter` is not set. */
+    truncateOnDelimiter: Uint8Array;
+    leadingEllipsis: boolean;
+}
+
+/** Measurement environment: font widths at device resolution plus the app/device scale factors. */
+export interface LayoutEnv {
+    width: WidthFn;
+    /** `RESOLUTION_AUTO_SCALE_FACTOR`: app pixels to device pixels (1, 1.5 or 2/3). */
+    autoScale: number;
+    /** `RESOLUTION_AUTO_SCALE_FACTOR_INV`: device pixels to app pixels. */
+    autoScaleInv: number;
+}

package/src/utf8.ts

@@ -0,0 +1,11 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+// The only place that touches TextEncoder / TextDecoder, so a host without them can swap this file.
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder("utf-8");
+
+export const encodeUtf8 = (text: string): Uint8Array => encoder.encode(text);
+
+export const decodeUtf8 = (bytes: Uint8Array): string => decoder.decode(bytes);

package/src/wrap-text.ts

@@ -0,0 +1,120 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+
+import { findCharBoundary, findWordBreak } from "./break-search";
+import { at, firstLineBreak, isSpaceNotNewline, normalizeWrapText } from "./bytes";
+import { ellipsizeText } from "./ellipsize";
+import type { BreakConfig, LayoutEnv } from "./types";
+
+const fround = Math.fround;
+
+export interface WrapParams {
+    /** Box width in app pixels. Must be greater than zero. */
+    width: number;
+    /** `mHeight` in app pixels: `Number.POSITIVE_INFINITY` stands for the firmware's `FLOAT_MAX`. */
+    height: number;
+    lineHeight: number;
+    lineSpacing: number;
+    displayPartialLines: boolean;
+}
+
+export interface WrapResult {
+    lines: Uint8Array[];
+    ellipsized: boolean;
+}
+
+/**
+ * `Label::wrapText`, verbatim: per line, a hinted binary search over break positions, each candidate measured as
+ * a whole substring; a character-level search when no break position fits; and the last line the height allows is
+ * ellipsized. Includes the firmware's `max = len - 1` assumption and the "cannot even display one character" exit.
+ */
+export function wrapText(raw: Uint8Array, params: WrapParams, cfg: BreakConfig, env: LayoutEnv): WrapResult {
+    const { width, height: boxHeight, lineHeight, lineSpacing, displayPartialLines } = params;
+    let remaining = normalizeWrapText(raw);
+    const scaledWidth = env.autoScale !== 1 ? fround(env.autoScale * width) : width;
+
+    const lines: Uint8Array[] = [];
+    let height = 0;
+    let lastNumChars = 100;
+    let ellipsized = false;
+
+    for (;;) {
+        if (displayPartialLines) {
+            if (height > boxHeight) break;
+        } else if (fround(fround(height + 2 * lineHeight) + lineSpacing) > boxHeight) {
+            const last = ellipsizeText(remaining, width, cfg, env);
+            lines.push(last.text);
+            ellipsized = last.ellipsized;
+            break;
+        }
+
+        const newlinePos = firstLineBreak(remaining);
+        if (newlinePos < 0 && env.width(remaining) <= scaledWidth) {
+            lines.push(remaining);
+            break;
+        }
+
+        const numChars = remaining.length;
+        if (numChars === 0) break;
+
+        let max = numChars - 1;
+        let min = 0;
+
+        if (newlinePos >= 0) {
+            max = newlinePos;
+            const upToNewline = remaining.slice(0, newlinePos);
+            const lineTest = lastNumChars + 20;
+            let skipTest = false;
+            if (newlinePos > lineTest && env.width(upToNewline.slice(0, lineTest)) > scaledWidth) skipTest = true;
+            if (!skipTest && env.width(upToNewline) <= scaledWidth) min = max;
+        }
+
+        const origMax = max;
+        let testNum = 0;
+        while (min + 1 < max) {
+            let mid: number;
+            if (testNum === 0) {
+                mid = lastNumChars + 15;
+                if (mid < min || mid > max) mid = (max + min) >> 1;
+                testNum++;
+            } else if (testNum === 1) {
+                mid = lastNumChars - 15;
+                if (mid < min || mid > max) mid = (max + min) >> 1;
+                testNum++;
+            } else {
+                mid = (max + min) >> 1;
+            }
+            mid = findWordBreak(remaining, min, mid, max, cfg);
+            if (mid < 0) break;
+
+            if (env.width(remaining.slice(0, mid)) <= scaledWidth) min = mid;
+            else max = mid;
+        }
+
+        if (min === 0) {
+            while (min + 1 < max) {
+                const mid = findCharBoundary(remaining, min, (max + min) >> 1, max);
+                if (mid < 0) break;
+                if (env.width(remaining.slice(0, mid)) <= scaledWidth) min = mid;
+                else max = mid;
+            }
+        } else if (min !== origMax) {
+            lastNumChars = min;
+        }
+
+        lines.push(remaining.slice(0, min));
+
+        const lastChar = at(remaining, min);
+        if (lastChar === 10 || lastChar === 13) {
+            min++;
+        } else {
+            while (min < numChars && isSpaceNotNewline(remaining[min])) min++;
+        }
+
+        if (min === 0) break;
+        remaining = remaining.slice(min);
+        height = fround(height + lineHeight + lineSpacing);
+    }
+
+    return { lines, ellipsized };
+}