linegauge 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ofri Peretz
+
+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,9 +1,16 @@
 # linegauge
 
-**Not yet released, and not yet on the roadmap.** This version reserves the name. The layer,
-its incumbents and the measurements behind it are documented in
-[`.sdlc/research/candidate-layers.md`](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/research/candidate-layers.md).
-An intent and a working release follow if and when the roadmap takes it up.
+**Not yet released.** This version reserves the name. The layer is planned as wave **F1** of the
+foundation tier: its intent and design are at
+[`.sdlc/intents/linegauge/`](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/intents/linegauge/),
+under the umbrella
+[`cli-foundation-stack`](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/intents/cli-foundation-stack/),
+and the measurements behind it are in
+[`candidate-layers.md`](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/research/candidate-layers.md)
+and
+[`replacement-map.md`](https://github.com/ofri-peretz/burgee/blob/main/.sdlc/research/replacement-map.md).
+Both artifacts are `draft`; the human gate has not run, and no working release ships before
+burgee's compatibility scoreboard is public.
 
 A **line gauge** is the printer's ruler — the steel rule marked in picas and points that a compositor uses to measure a line of type and check it fits the measure it was set to.
 
@@ -11,7 +18,7 @@ That is this package's whole job. Width, wrap, truncate and slice are one proble
 
 ## What it will be
 
-- **One package, not eleven.** `width` · `wrap` · `truncate` · `slice` · `strip` · `widest`. The incumbents split this across `string-width`, `wrap-ansi`, `strip-ansi`, `slice-ansi`, `cli-truncate`, `widest-line`, `string-length`, `wcwidth`, `eastasianwidth` and `get-east-asian-width`.
+- **One package, not twelve.** `width` · `wrap` · `truncate` · `slice` · `strip` · `widest`. The incumbents split this across `strip-ansi`, `string-width`, `ansi-regex`, `wrap-ansi`, `emoji-regex`, `slice-ansi`, `get-east-asian-width`, `eastasianwidth`, `string-length`, `wcwidth`, `cli-truncate` and `widest-line` — **2.16 B weekly downloads** between them.
 - **Grapheme-correct by construction.** ZWJ families, regional-indicator flags, skin-tone modifiers, keycaps, combining marks and East Asian wide characters, over the platform's own `Intl.Segmenter`.
 - **Fast path for ASCII.** A byte scan when the string has no non-ASCII code unit; the segmenter only when it earns its cost.
 - **Drop-in paths** for `string-width`, `wrap-ansi`, `strip-ansi` and `slice-ansi`, graded by their own suites.

package/dist/index.d.ts

@@ -1,7 +1,24 @@
 /**
- * linegauge — name reserved, not yet on the roadmap. The layer and the measurements
- * behind it are documented in .sdlc/research/candidate-layers.md in the burgee
- * repository. Until an intent is opened this entry exports only its own name, so
- * that importing it costs nothing and promises nothing.
+ * Copyright (c) 2026 Ofri Peretz
+ * Licensed under the MIT License. Use of this source code is governed by the
+ * MIT license that can be found in the LICENSE file.
  */
-export declare const name: "linegauge";
+/**
+ * linegauge — how much of a terminal line a string occupies, and how to fold it.
+ *
+ * F1 of the foundation tier, built by moving rather than by writing: `width` and `wrap`
+ * were already in `flagstaff`, already ported, already graded differentially against
+ * `string-width` and `wrap-ansi`. This package is where they belong, because measuring a
+ * line is not drawing one — a spinner, a box, a table and a status line all need the
+ * measurement, and nothing about the measurement needs any of them.
+ *
+ * The default export is `width`, byte-for-byte call-compatible with `string-width`'s
+ * default (R8), so `overrides: { "string-width": "npm:linegauge@^1" }` resolves.
+ *
+ * Not here yet, and each still at the Design→Build gate: `slice`, `truncate`, `widest`,
+ * the R2 ASCII fast path, and an exported `strip`. This release is the move, so that a
+ * green `flagstaff` across the deletion proves the consolidation is real before anything
+ * new is written on top of it.
+ */
+export { lineCount, measure, width, width as default } from './width.js';
+export { wrap, type WrapOptions } from './wrap.js';

package/dist/index.js

@@ -1,8 +1,25 @@
 /**
- * linegauge — name reserved, not yet on the roadmap. The layer and the measurements
- * behind it are documented in .sdlc/research/candidate-layers.md in the burgee
- * repository. Until an intent is opened this entry exports only its own name, so
- * that importing it costs nothing and promises nothing.
+ * Copyright (c) 2026 Ofri Peretz
+ * Licensed under the MIT License. Use of this source code is governed by the
+ * MIT license that can be found in the LICENSE file.
  */
-export const name = 'linegauge';
+/**
+ * linegauge — how much of a terminal line a string occupies, and how to fold it.
+ *
+ * F1 of the foundation tier, built by moving rather than by writing: `width` and `wrap`
+ * were already in `flagstaff`, already ported, already graded differentially against
+ * `string-width` and `wrap-ansi`. This package is where they belong, because measuring a
+ * line is not drawing one — a spinner, a box, a table and a status line all need the
+ * measurement, and nothing about the measurement needs any of them.
+ *
+ * The default export is `width`, byte-for-byte call-compatible with `string-width`'s
+ * default (R8), so `overrides: { "string-width": "npm:linegauge@^1" }` resolves.
+ *
+ * Not here yet, and each still at the Design→Build gate: `slice`, `truncate`, `widest`,
+ * the R2 ASCII fast path, and an exported `strip`. This release is the move, so that a
+ * green `flagstaff` across the deletion proves the consolidation is real before anything
+ * new is written on top of it.
+ */
+export { lineCount, measure, width, width as default } from './width.js';
+export { wrap } from './wrap.js';
 //# sourceMappingURL=index.js.map

package/dist/width.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Columns a string of *plain* text occupies — no escape scan. The wrapper below has
+ * already split its input into text runs and complete sequences, so rescanning would only
+ * give a malformed sequence a second chance to be mistaken for one.
+ */
+export declare function measure(text: string): number;
+/** How many terminal columns `input` occupies once its escape sequences are removed. */
+export declare function width(input: string): number;
+/**
+ * Lines a string occupies in a terminal `columns` wide — the measurement the frame loop
+ * actually asks for. An empty line still occupies one.
+ */
+export declare function lineCount(text: string, columns: number): number;

package/dist/width.js

@@ -0,0 +1,128 @@
+/**
+ * Display width of a string in terminal columns (R7).
+ *
+ * A column count is the one measurement the output stack cannot avoid: a spinner has to
+ * know how many lines its frame occupied before it can erase them, and a box has to know
+ * where its right edge falls. `string-width` does this in four packages; here it is one
+ * function over `Intl.Segmenter` and a range table, because a package this size is not
+ * worth a dependency tree (U5).
+ *
+ * The rules, in the order a cluster meets them:
+ *   1. ANSI and other control sequences are not printed — `stripVTControlCharacters`.
+ *   2. A grapheme cluster made only of ignorable, control, mark or surrogate code points
+ *      occupies no column.
+ *   3. An RGI emoji sequence is two columns, however many code points it is made of.
+ *   4. Otherwise the East Asian Width of the cluster's first visible code point, plus the
+ *      halfwidth-and-fullwidth forms trailing it in the same cluster (a dakuten).
+ *
+ * Ambiguous-width characters are counted narrow, which is what a terminal does unless it
+ * has been told it is rendering an East Asian locale. `string-width` makes that an option;
+ * nothing above this function has ever needed the other answer, so it is not one here.
+ */
+import { stripVTControlCharacters } from 'node:util';
+/**
+ * East Asian Wide and Fullwidth, as sorted `[low, high]` pairs flattened into one array —
+ * Unicode 17's W and F categories, merged where they touch. Generated from the same
+ * `EastAsianWidth.txt` derivation everyone uses; a binary search over 122 ranges is the
+ * whole lookup.
+ */
+const WIDE = [
+    0x1100, 0x115F, 0x231A, 0x231B, 0x2329, 0x232A, 0x23E9, 0x23EC, 0x23F0, 0x23F0,
+    0x23F3, 0x23F3, 0x25FD, 0x25FE, 0x2614, 0x2615, 0x2630, 0x2637, 0x2648, 0x2653,
+    0x267F, 0x267F, 0x268A, 0x268F, 0x2693, 0x2693, 0x26A1, 0x26A1, 0x26AA, 0x26AB,
+    0x26BD, 0x26BE, 0x26C4, 0x26C5, 0x26CE, 0x26CE, 0x26D4, 0x26D4, 0x26EA, 0x26EA,
+    0x26F2, 0x26F3, 0x26F5, 0x26F5, 0x26FA, 0x26FA, 0x26FD, 0x26FD, 0x2705, 0x2705,
+    0x270A, 0x270B, 0x2728, 0x2728, 0x274C, 0x274C, 0x274E, 0x274E, 0x2753, 0x2755,
+    0x2757, 0x2757, 0x2795, 0x2797, 0x27B0, 0x27B0, 0x27BF, 0x27BF, 0x2B1B, 0x2B1C,
+    0x2B50, 0x2B50, 0x2B55, 0x2B55, 0x2E80, 0x2E99, 0x2E9B, 0x2EF3, 0x2F00, 0x2FD5,
+    0x2FF0, 0x303E, 0x3041, 0x3096, 0x3099, 0x30FF, 0x3105, 0x312F, 0x3131, 0x318E,
+    0x3190, 0x31E5, 0x31EF, 0x321E, 0x3220, 0x3247, 0x3250, 0xA48C, 0xA490, 0xA4C6,
+    0xA960, 0xA97C, 0xAC00, 0xD7A3, 0xF900, 0xFAFF, 0xFE10, 0xFE19, 0xFE30, 0xFE52,
+    0xFE54, 0xFE66, 0xFE68, 0xFE6B, 0xFF01, 0xFF60, 0xFFE0, 0xFFE6, 0x16FE0, 0x16FE4,
+    0x16FF0, 0x16FF1, 0x17000, 0x187F7, 0x18800, 0x18CD5, 0x18CFF, 0x18D08, 0x1AFF0, 0x1AFF3,
+    0x1AFF5, 0x1AFFB, 0x1AFFD, 0x1AFFE, 0x1B000, 0x1B122, 0x1B132, 0x1B132, 0x1B150, 0x1B152,
+    0x1B155, 0x1B155, 0x1B164, 0x1B167, 0x1B170, 0x1B2FB, 0x1D300, 0x1D356, 0x1D360, 0x1D376,
+    0x1F004, 0x1F004, 0x1F0CF, 0x1F0CF, 0x1F18E, 0x1F18E, 0x1F191, 0x1F19A, 0x1F200, 0x1F202,
+    0x1F210, 0x1F23B, 0x1F240, 0x1F248, 0x1F250, 0x1F251, 0x1F260, 0x1F265, 0x1F300, 0x1F320,
+    0x1F32D, 0x1F335, 0x1F337, 0x1F37C, 0x1F37E, 0x1F393, 0x1F3A0, 0x1F3CA, 0x1F3CF, 0x1F3D3,
+    0x1F3E0, 0x1F3F0, 0x1F3F4, 0x1F3F4, 0x1F3F8, 0x1F43E, 0x1F440, 0x1F440, 0x1F442, 0x1F4FC,
+    0x1F4FF, 0x1F53D, 0x1F54B, 0x1F54E, 0x1F550, 0x1F567, 0x1F57A, 0x1F57A, 0x1F595, 0x1F596,
+    0x1F5A4, 0x1F5A4, 0x1F5FB, 0x1F64F, 0x1F680, 0x1F6C5, 0x1F6CC, 0x1F6CC, 0x1F6D0, 0x1F6D2,
+    0x1F6D5, 0x1F6D7, 0x1F6DC, 0x1F6DF, 0x1F6EB, 0x1F6EC, 0x1F6F4, 0x1F6FC, 0x1F7E0, 0x1F7EB,
+    0x1F7F0, 0x1F7F0, 0x1F90C, 0x1F93A, 0x1F93C, 0x1F945, 0x1F947, 0x1F9FF, 0x1FA70, 0x1FA7C,
+    0x1FA80, 0x1FA89, 0x1FA8F, 0x1FAC6, 0x1FACE, 0x1FADC, 0x1FADF, 0x1FAE9, 0x1FAF0, 0x1FAF8,
+    0x20000, 0x2FFFD, 0x30000, 0x3FFFD,
+];
+const NARROW = 1;
+const WIDE_COLUMNS = 2;
+/** Half the flat array is lows, so a step over pairs. */
+const PAIR = 2;
+function isWide(codePoint) {
+    let low = 0;
+    let high = WIDE.length / PAIR - 1;
+    while (low <= high) {
+        const mid = (low + high) >> 1;
+        const start = WIDE[mid * PAIR] ?? 0;
+        const end = WIDE[mid * PAIR + 1] ?? 0;
+        if (codePoint < start)
+            high = mid - 1;
+        else if (codePoint > end)
+            low = mid + 1;
+        else
+            return true;
+    }
+    return false;
+}
+// `v`-mode properties: the whole point of using them is that Node ships the tables.
+const ZERO_WIDTH_CLUSTER = /^(?:\p{Default_Ignorable_Code_Point}|\p{Control}|\p{Mark}|\p{Surrogate})+$/v;
+const LEADING_NON_PRINTING = /^[\p{Default_Ignorable_Code_Point}\p{Control}\p{Format}\p{Mark}\p{Surrogate}]+/v;
+const RGI_EMOJI = /^\p{RGI_Emoji}$/v;
+/** The Halfwidth and Fullwidth Forms block, which a cluster can carry after its base. */
+const FORMS_FIRST = 0xff00;
+const FORMS_LAST = 0xffef;
+const segmenter = new Intl.Segmenter();
+/** Columns a cluster's trailing fullwidth forms add — `ｶﾞ` is a base plus a wide mark. */
+function trailingForms(cluster) {
+    let extra = 0;
+    for (const character of [...cluster].slice(1)) {
+        const codePoint = character.codePointAt(0) ?? 0;
+        if (codePoint >= FORMS_FIRST && codePoint <= FORMS_LAST)
+            extra += isWide(codePoint) ? WIDE_COLUMNS : NARROW;
+    }
+    return extra;
+}
+/**
+ * Columns a string of *plain* text occupies — no escape scan. The wrapper below has
+ * already split its input into text runs and complete sequences, so rescanning would only
+ * give a malformed sequence a second chance to be mistaken for one.
+ */
+export function measure(text) {
+    let columns = 0;
+    for (const { segment } of segmenter.segment(text)) {
+        if (ZERO_WIDTH_CLUSTER.test(segment))
+            continue;
+        if (RGI_EMOJI.test(segment)) {
+            columns += WIDE_COLUMNS;
+            continue;
+        }
+        const codePoint = segment.replace(LEADING_NON_PRINTING, '').codePointAt(0) ?? 0;
+        columns += isWide(codePoint) ? WIDE_COLUMNS : NARROW;
+        columns += trailingForms(segment);
+    }
+    return columns;
+}
+/** How many terminal columns `input` occupies once its escape sequences are removed. */
+export function width(input) {
+    return input === '' ? 0 : measure(stripVTControlCharacters(input));
+}
+/**
+ * Lines a string occupies in a terminal `columns` wide — the measurement the frame loop
+ * actually asks for. An empty line still occupies one.
+ */
+export function lineCount(text, columns) {
+    let count = 0;
+    for (const line of stripVTControlCharacters(text).split('\n'))
+        count += Math.max(1, Math.ceil(width(line) / columns));
+    return count;
+}
+//# sourceMappingURL=width.js.map

package/dist/wrap.d.ts

@@ -0,0 +1,10 @@
+export interface WrapOptions {
+    /** Trim leading and trailing whitespace from each row. Default true. */
+    trim?: boolean;
+    /** Break a word longer than `columns` rather than let it overflow. Default false. */
+    hard?: boolean;
+    /** Break on any character rather than at word boundaries. Default true. */
+    wordWrap?: boolean;
+}
+/** Wrap `string` to `columns`, keeping its ANSI intact and each row self-contained. */
+export declare function wrap(string: string, columns: number, options?: WrapOptions): string;

package/dist/wrap.js

@@ -0,0 +1,523 @@
+/**
+ * Wrapping text that carries ANSI, ported from wrap-ansi 10 — the third dependency the
+ * render façades share, after the spinner corpus and the width function (R7, R10).
+ *
+ * The hard part is not the arithmetic, it is that a style opened on one row must not leak
+ * into the next: a terminal that reflows, a pager, or an agent reading one line at a time
+ * all see rows independently. So every row closes the styles it inherited and the next row
+ * reopens them, which has a second use here — after wrapping, **each row is self-contained**,
+ * and dropping leading rows needs no ANSI state tracking at all. `flagstaff/log-update`
+ * relies on exactly that, which is why it carries no port of `slice-ansi`.
+ *
+ * Graded differentially against the real `wrap-ansi` in `wrap.test.ts`, the way `width.ts`
+ * is graded against `string-width`: the incumbent is the specification.
+ */
+import { measure } from './width.js';
+const ESC = '\u001B';
+const BELL = '\u0007';
+/** The single-byte C1 form of `ESC [`, which a terminal accepts and a suite will send. */
+const C1_CSI = '\u009B';
+const CSI = '[';
+const OSC = ']';
+const SGR_TERMINATOR = 'm';
+const SGR_RESET = 0;
+const SGR_RESET_FOREGROUND = 39;
+const SGR_RESET_BACKGROUND = 49;
+const SGR_RESET_UNDERLINE_COLOR = 59;
+const SGR_FOREGROUND_EXTENDED = 38;
+const SGR_BACKGROUND_EXTENDED = 48;
+const SGR_UNDERLINE_COLOR_EXTENDED = 58;
+const SGR_COLOR_MODE_RGB = 2;
+const SGR_COLOR_MODE_256 = 5;
+const FOREGROUND_FIRST = 30;
+const FOREGROUND_LAST = 37;
+const FOREGROUND_BRIGHT_FIRST = 90;
+const FOREGROUND_BRIGHT_LAST = 97;
+const BACKGROUND_FIRST = 40;
+const BACKGROUND_LAST = 47;
+const BACKGROUND_BRIGHT_FIRST = 100;
+const BACKGROUND_BRIGHT_LAST = 107;
+/** How many columns a tab advances to the next stop. */
+const TAB_SIZE = 8;
+/** `38;5;n` — the code, the mode, and one index. */
+const COLOR_256_PARTS = 3;
+/** `38;2;r;g;b` — the code, the mode, and three components. */
+const COLOR_RGB_PARTS = 3;
+/** `38:2::r:g:b` carries a colour space between the mode and the components. */
+const COLON_RGB_WITH_SPACE = 6;
+const ESCAPES = new Set([ESC, C1_CSI]);
+const ESCAPE_CHARACTERS = [...ESCAPES].join('');
+const CSI_INTRODUCER = `(?:${ESC}\\${CSI}|${C1_CSI})`;
+const CSI_PARAMETERS = '[0-?]*[ -/]*[@-~]';
+const SGR_PARAMETERS = `(?<sgr>[0-9;:]*)${SGR_TERMINATOR}`;
+const OSC_TERMINATOR = `(?:${BELL}|${ESC}\\\\)`;
+const OSC_PAYLOAD = String.raw `[^\u0000-\u001F\u007F-\u009F]*`;
+/** `OSC 8 ; params ; URI ST` — a hyperlink, whose URI is tracked so a row can reopen it. */
+const LINK_PARAMETERS = String.raw `8;(?<parameters>[^;\u0000-\u001F\u007F-\u009F]*);(?<uri>${OSC_PAYLOAD})${OSC_TERMINATOR}`;
+// Deliberately not a terminal emulator: semicolon-delimited SGR, colon-delimited extended
+// colour and OSC 8 links are understood; every other complete CSI or OSC command is carried
+// through as an opaque zero-width unit, and anything that only looks like an introducer
+// stays plain text. `y` (sticky), so a match is anchored where the scan asked.
+const ANSI_ESCAPE = new RegExp(`${CSI_INTRODUCER}(?:${SGR_PARAMETERS}|${CSI_PARAMETERS})|${ESC}\\${OSC}(?:${LINK_PARAMETERS}|${OSC_PAYLOAD}${OSC_TERMINATOR})`, 'y');
+const ESCAPE_INTRODUCER = new RegExp(`[${ESCAPE_CHARACTERS}]`, 'g');
+const ROW_BOUNDARY = new RegExp(`[\\n${ESCAPE_CHARACTERS}]`, 'g');
+/** Every printable ASCII character is its own cluster of width one — skip the segmenter. */
+const ASCII_PRINTABLE = /^[ -~]*$/;
+/**
+ * Which SGR code closes which modifier. This is ECMA-48, not any library's table — bold
+ * opens with 1 and closes with 22 wherever you read it — so it lives here rather than
+ * being imported, which keeps `wrap()` free of `roundel/chalk` and takes 18 KB off every
+ * subpath that wraps. The colour families close with 39, 49 and 59 and are handled by name
+ * above, before this map is consulted.
+ */
+const MODIFIER_CLOSE = new Map([
+    [1, 22],
+    [2, 22],
+    [3, 23],
+    [4, 24],
+    [7, 27],
+    [8, 28],
+    [9, 29],
+    [53, 55],
+]);
+const MODIFIER_CLOSE_CODES = new Set(MODIFIER_CLOSE.values());
+const segmenter = new Intl.Segmenter();
+const sgr = (code) => `${ESC}${CSI}${code}${SGR_TERMINATOR}`;
+const hyperlink = (url, parameters = '') => `${ESC}${OSC}8;${parameters};${url}${BELL}`;
+/** The complete escape sequence starting at `index`, or nothing when none starts there. */
+function matchEscape(string, index) {
+    if (!ESCAPES.has(string[index] ?? ''))
+        return undefined;
+    ANSI_ESCAPE.lastIndex = index;
+    return ANSI_ESCAPE.exec(string) ?? undefined;
+}
+/**
+ * Walk a string as alternating runs of plain text and complete escape sequences. A
+ * character that looks like an introducer but starts no valid sequence stays plain text.
+ */
+function forEachSegment(string, onPlainText, onEscape = () => undefined) {
+    let plainStart = 0;
+    let index = 0;
+    while (index < string.length) {
+        ESCAPE_INTRODUCER.lastIndex = index;
+        const introducer = ESCAPE_INTRODUCER.exec(string);
+        if (introducer === null)
+            break;
+        const escape = matchEscape(string, introducer.index);
+        if (escape === undefined) {
+            index = introducer.index + 1;
+            continue;
+        }
+        if (introducer.index > plainStart)
+            onPlainText(string.slice(plainStart, introducer.index));
+        onEscape(escape[0]);
+        index = introducer.index + escape[0].length;
+        plainStart = index;
+    }
+    if (plainStart < string.length)
+        onPlainText(string.slice(plainStart));
+}
+/** The visible width of a string, escape sequences ignored. */
+function visibleWidth(string) {
+    let plainText = '';
+    forEachSegment(string, (part) => {
+        plainText += part;
+    });
+    return measure(plainText);
+}
+/**
+ * Escape sequences, which are zero width and must never be split, and grapheme clusters.
+ * A sequence written *inside* a cluster splits it — the supported boundary is between
+ * clusters and sequences, not within one.
+ */
+function tokenize(string) {
+    const tokens = [];
+    forEachSegment(string, (plainText) => {
+        if (ASCII_PRINTABLE.test(plainText)) {
+            for (const character of plainText)
+                tokens.push({ value: character, width: 1 });
+            return;
+        }
+        for (const { segment } of segmenter.segment(plainText))
+            tokens.push({ value: segment, width: measure(segment) });
+    }, (escape) => tokens.push({ value: escape, width: 0 }));
+    return tokens;
+}
+/** Split on spaces, ignoring spaces that appear inside a recognised sequence. */
+function splitWords(string) {
+    let current = { value: '', plainText: '', width: 0 };
+    const words = [current];
+    forEachSegment(string, (plainText) => {
+        const parts = plainText.split(' ');
+        current.value += parts[0] ?? '';
+        current.plainText += parts[0] ?? '';
+        for (let index = 1; index < parts.length; index += 1) {
+            const part = parts[index] ?? '';
+            current = { value: part, plainText: part, width: 0 };
+            words.push(current);
+        }
+    }, (escape) => {
+        current.value += escape;
+    });
+    // Measured once per word rather than per run, so a cluster an escape splits counts once.
+    for (const word of words)
+        word.width = measure(word.plainText);
+    return words;
+}
+const isDigits = (value) => /^\d+$/.test(value);
+/** `38:5:9` and `38:2::r:g:b` — the colon form, which carries its arguments in one parameter. */
+function colonColorToken(parameter) {
+    const parts = parameter.split(':');
+    const code = Number.parseInt(parts[0] ?? '', 10);
+    const mode = Number.parseInt(parts[1] ?? '', 10);
+    if (![SGR_FOREGROUND_EXTENDED, SGR_BACKGROUND_EXTENDED, SGR_UNDERLINE_COLOR_EXTENDED].includes(code))
+        return undefined;
+    if (mode === SGR_COLOR_MODE_256 && parts.length === COLOR_256_PARTS && isDigits(parts[2] ?? '')) {
+        return { code, open: parameter, hasArguments: true };
+    }
+    if (mode !== SGR_COLOR_MODE_RGB)
+        return undefined;
+    const withSpace = parts.length === COLON_RGB_WITH_SPACE;
+    const components = withSpace ? parts.slice(3) : parts.slice(2);
+    const colorSpace = withSpace ? parts[2] : undefined;
+    if (components.length === COLOR_RGB_PARTS && components.every(isDigits) && (colorSpace === undefined || /^\d*$/.test(colorSpace))) {
+        return { code, open: parameter, hasArguments: true };
+    }
+    return undefined;
+}
+/** One extended-colour parameter run, `38;5;n` or `38;2;r;g;b`, or nothing if malformed. */
+function extendedColorToken(code, parameters, index) {
+    const mode = Number.parseInt(parameters[index + 1] ?? '', 10);
+    const first = Number.parseInt(parameters[index + 2] ?? '', 10);
+    if (mode === SGR_COLOR_MODE_256 && Number.isFinite(first)) {
+        return { token: { code, open: [code, mode, first].join(';'), hasArguments: true }, consumed: 2 };
+    }
+    const green = Number.parseInt(parameters[index + 3] ?? '', 10);
+    const blue = Number.parseInt(parameters[index + 4] ?? '', 10);
+    if (mode === SGR_COLOR_MODE_RGB && Number.isFinite(first) && Number.isFinite(green) && Number.isFinite(blue)) {
+        return { token: { code, open: [code, mode, first, green, blue].join(';'), hasArguments: true }, consumed: 4 };
+    }
+    return undefined;
+}
+const isExtendedColor = (code) => code === SGR_FOREGROUND_EXTENDED || code === SGR_BACKGROUND_EXTENDED || code === SGR_UNDERLINE_COLOR_EXTENDED;
+function sgrTokens(parameters) {
+    const parts = parameters.split(';');
+    const tokens = [];
+    for (let index = 0; index < parts.length; index += 1) {
+        const parameter = parts[index] ?? '';
+        if (parameter.includes(':')) {
+            const token = colonColorToken(parameter);
+            if (token !== undefined)
+                tokens.push(token);
+            continue;
+        }
+        const code = parameter === '' ? SGR_RESET : Number.parseInt(parameter, 10);
+        if (!Number.isFinite(code))
+            continue;
+        if (isExtendedColor(code)) {
+            if (index + 1 >= parts.length)
+                break;
+            const extended = extendedColorToken(code, parts, index);
+            if (extended === undefined)
+                break;
+            tokens.push(extended.token);
+            index += extended.consumed;
+            continue;
+        }
+        tokens.push({ code, open: String(code), hasArguments: false });
+    }
+    return tokens;
+}
+function removeFamily(active, family) {
+    const at = active.findIndex((style) => style.family === family);
+    if (at !== -1)
+        active.splice(at, 1);
+}
+function colorStyle(token) {
+    const { code, open, hasArguments } = token;
+    if ((code >= FOREGROUND_FIRST && code <= FOREGROUND_LAST) || (code >= FOREGROUND_BRIGHT_FIRST && code <= FOREGROUND_BRIGHT_LAST) || (code === SGR_FOREGROUND_EXTENDED && hasArguments)) {
+        return { family: 'foreground', open, close: SGR_RESET_FOREGROUND };
+    }
+    if ((code >= BACKGROUND_FIRST && code <= BACKGROUND_LAST) || (code >= BACKGROUND_BRIGHT_FIRST && code <= BACKGROUND_BRIGHT_LAST) || (code === SGR_BACKGROUND_EXTENDED && hasArguments)) {
+        return { family: 'background', open, close: SGR_RESET_BACKGROUND };
+    }
+    if (code === SGR_UNDERLINE_COLOR_EXTENDED && hasArguments) {
+        return { family: 'underlineColor', open, close: SGR_RESET_UNDERLINE_COLOR };
+    }
+    return undefined;
+}
+/** True when the code closed something rather than opening it. */
+function applyResetCode(code, active) {
+    if (code === SGR_RESET) {
+        active.length = 0;
+        return true;
+    }
+    if (code === SGR_RESET_FOREGROUND) {
+        removeFamily(active, 'foreground');
+        return true;
+    }
+    if (code === SGR_RESET_BACKGROUND) {
+        removeFamily(active, 'background');
+        return true;
+    }
+    if (code === SGR_RESET_UNDERLINE_COLOR) {
+        removeFamily(active, 'underlineColor');
+        return true;
+    }
+    if (MODIFIER_CLOSE_CODES.has(code)) {
+        // One close code can end several modifiers — `22` ends both bold and dim.
+        for (let index = active.length - 1; index >= 0; index -= 1) {
+            const style = active[index];
+            if (style !== undefined && style.family.startsWith('modifier-') && style.close === code)
+                active.splice(index, 1);
+        }
+        return true;
+    }
+    return false;
+}
+function applyToken(token, active) {
+    if (applyResetCode(token.code, active))
+        return;
+    const color = colorStyle(token);
+    if (color !== undefined) {
+        removeFamily(active, color.family);
+        active.push(color);
+        return;
+    }
+    const close = MODIFIER_CLOSE.get(token.code);
+    if (close !== undefined && close !== SGR_RESET) {
+        const family = `modifier-${token.code}`;
+        removeFamily(active, family);
+        active.push({ family, open: token.open, close });
+    }
+}
+const applyParameters = (parameters, active) => {
+    for (const token of sgrTokens(parameters))
+        applyToken(token, active);
+};
+const applyResets = (parameters, active) => {
+    for (const { code } of sgrTokens(parameters))
+        applyResetCode(code, active);
+};
+/** A row that opens with its own resets should not have them undone by the reopening. */
+function applyLeadingResets(string, startIndex, active) {
+    let index = startIndex;
+    while (index < string.length) {
+        const match = matchEscape(string, index);
+        if (match === undefined)
+            break;
+        if (match.groups?.['sgr'] !== undefined)
+            applyResets(match.groups['sgr'], active);
+        index += match[0].length;
+    }
+}
+const closingSequence = (active) => [...active].reverse().map((style) => sgr(style.close)).join('');
+const openingSequence = (active) => active.map((style) => sgr(style.open)).join('');
+/**
+ * Break one long word across rows. Takes the visible width of the row it starts on and
+ * returns the width of the row it ends on, so the caller never measures a row itself.
+ */
+function wrapWord(rows, word, columns, rowWidth) {
+    const tokens = tokenize(word);
+    let visible = rowWidth;
+    for (const [index, token] of tokens.entries()) {
+        // Sequences and combining marks are zero width, so they stay on the current row.
+        if (token.width > 0 && visible > 0 && visible + token.width > columns) {
+            rows.push('');
+            visible = 0;
+        }
+        rows[rows.length - 1] += token.value;
+        visible += token.width;
+        if (visible === columns && index < tokens.length - 1) {
+            rows.push('');
+            visible = 0;
+        }
+    }
+    // The last row copied over can be nothing but escape characters.
+    const last = rows.at(-1) ?? '';
+    if (!visible && last.length > 0 && rows.length > 1)
+        rows[rows.length - 2] += rows.pop() ?? '';
+    // Tokens are measured one at a time, so a cluster an escape splits counts once per part.
+    // Only the finished row gives the true width, and it is at most one row to measure.
+    return visibleWidth(rows.at(-1) ?? '');
+}
+/** Drop the spaces trailing the last visible character, keeping the sequences among them. */
+function trimVisibleEnd(string) {
+    if (!string.includes(' '))
+        return string;
+    const segments = [];
+    forEachSegment(string, (plainText) => segments.push({ value: plainText, isEscape: false }), (escape) => segments.push({ value: escape, isEscape: true }));
+    for (let index = segments.length - 1; index >= 0; index -= 1) {
+        const segment = segments[index];
+        if (segment === undefined || segment.isEscape)
+            continue;
+        // Scanned rather than matched: a trailing-space pattern backtracks quadratically.
+        let end = segment.value.length;
+        while (end > 0 && segment.value[end - 1] === ' ')
+            end -= 1;
+        segment.value = segment.value.slice(0, end);
+        if (measure(segment.value) > 0)
+            break;
+    }
+    return segments.map((segment) => segment.value).join('');
+}
+function expandTabs(line) {
+    if (!line.includes('\t'))
+        return line;
+    let visible = 0;
+    let expanded = '';
+    let sinceTab = '';
+    forEachSegment(line, (plainText) => {
+        const parts = plainText.split('\t');
+        for (const [index, part] of parts.entries()) {
+            expanded += part;
+            sinceTab += part;
+            if (index < parts.length - 1) {
+                visible += measure(sinceTab);
+                sinceTab = '';
+                const spaces = TAB_SIZE - (visible % TAB_SIZE);
+                expanded += ' '.repeat(spaces);
+                visible += spaces;
+            }
+        }
+    }, (escape) => {
+        expanded += escape;
+    });
+    return expanded;
+}
+/**
+ * Close the active styles and hyperlink before every row break and reopen them after, so
+ * each row stands on its own. Only sequences and newlines matter, so the string is scanned
+ * directly rather than segmented.
+ */
+function restoreStylesAcrossRows(preString) {
+    let out = '';
+    let activeHyperlink;
+    const active = [];
+    let index = 0;
+    let copied = 0;
+    while (index < preString.length) {
+        ROW_BOUNDARY.lastIndex = index;
+        const boundary = ROW_BOUNDARY.exec(preString);
+        if (boundary === null)
+            break;
+        index = boundary.index;
+        if (boundary[0] !== '\n') {
+            const escape = matchEscape(preString, index);
+            if (escape === undefined) {
+                index += 1;
+                continue;
+            }
+            const groups = escape.groups ?? {};
+            if (groups['sgr'] !== undefined)
+                applyParameters(groups['sgr'], active);
+            else if (groups['uri'] !== undefined)
+                activeHyperlink = groups['uri'].length === 0 ? undefined : { parameters: groups['parameters'] ?? '', uri: groups['uri'] };
+            index += escape[0].length;
+            continue;
+        }
+        // Everything up to the row break is copied verbatim, sequences included.
+        out += preString.slice(copied, index);
+        // An empty row never reopened anything, so there is nothing to close.
+        if (index > copied) {
+            if (activeHyperlink !== undefined)
+                out += hyperlink('');
+            out += closingSequence(active);
+        }
+        out += '\n';
+        index += 1;
+        copied = index;
+        // An empty row has nothing to style, so the styles stay closed until the next row with
+        // content; a trailing row break leaves no row at all.
+        if (index < preString.length && preString[index] !== '\n') {
+            const opening = [...active];
+            applyLeadingResets(preString, index, opening);
+            out += openingSequence(opening);
+            if (activeHyperlink !== undefined)
+                out += hyperlink(activeHyperlink.uri, activeHyperlink.parameters);
+        }
+    }
+    return out + preString.slice(copied);
+}
+/** Whether a word longer than the row should start on the next row instead of this one. */
+function shouldStartLongWordOnNextRow(wordWidth, columns, rowLength) {
+    const remaining = columns - rowLength;
+    const breaksStartingThisRow = 1 + Math.floor((wordWidth - remaining - 1) / columns);
+    const breaksStartingNextRow = Math.floor((wordWidth - 1) / columns);
+    return breaksStartingNextRow < breaksStartingThisRow;
+}
+/** One line of input — the caller has already split on newlines. */
+function wrapLine(string, columns, options) {
+    const trim = options.trim !== false;
+    if (trim && string.trim() === '')
+        return '';
+    const words = splitWords(string);
+    let rows = [''];
+    // Tracked as rows are built: remeasuring per word makes wrapping quadratic in the line.
+    let rowLength = 0;
+    // A row that already starts with content can never become trimmable again.
+    let trimmedRowIndex = -1;
+    let isFirstWord = true;
+    for (const word of words) {
+        const rowIndex = rows.length - 1;
+        if (trim && trimmedRowIndex !== rowIndex) {
+            const row = rows[rowIndex] ?? '';
+            const trimmedRow = row.trimStart();
+            if (trimmedRow.length !== row.length) {
+                rows[rowIndex] = trimmedRow;
+                rowLength = visibleWidth(trimmedRow);
+            }
+            if (trimmedRow.length > 0)
+                trimmedRowIndex = rowIndex;
+        }
+        if (isFirstWord) {
+            isFirstWord = false;
+        }
+        else {
+            if (rowLength >= columns && (options.wordWrap === false || !trim)) {
+                rows.push('');
+                rowLength = 0;
+            }
+            if (rowLength > 0 || !trim) {
+                rows[rows.length - 1] += ' ';
+                rowLength += 1;
+            }
+        }
+        // 'hard': a row is never allowed to extend past `columns`.
+        if (options.hard === true && options.wordWrap !== false && word.width > columns) {
+            if (shouldStartLongWordOnNextRow(word.width, columns, rowLength)) {
+                rows.push('');
+                rowLength = 0;
+            }
+            rowLength = wrapWord(rows, word.value, columns, rowLength);
+            continue;
+        }
+        if (rowLength + word.width > columns && rowLength > 0 && word.width > 0) {
+            if (options.wordWrap === false && rowLength < columns) {
+                rowLength = wrapWord(rows, word.value, columns, rowLength);
+                continue;
+            }
+            rows.push('');
+            rowLength = 0;
+        }
+        if (rowLength + word.width > columns && options.wordWrap === false) {
+            rowLength = wrapWord(rows, word.value, columns, rowLength);
+            continue;
+        }
+        rows[rows.length - 1] += word.value;
+        rowLength += word.width;
+    }
+    if (trim)
+        rows = rows.map((row) => trimVisibleEnd(row));
+    return restoreStylesAcrossRows(rows.join('\n'));
+}
+/** Wrap `string` to `columns`, keeping its ANSI intact and each row self-contained. */
+export function wrap(string, columns, options = {}) {
+    return String(string)
+        .normalize()
+        .replaceAll('\r\n', '\n')
+        .split('\n')
+        .map((line) => wrapLine(expandTabs(line), columns, options))
+        .join('\n');
+}
+//# sourceMappingURL=wrap.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "linegauge",
-  "version": "0.0.1",
-  "description": "The width of material a saw removes in a cut. Measuring, wrapping, truncating and slicing styled terminal text without the edge fraying \u2014 grapheme-correct over Intl.Segmenter. Drop-in paths for string-width, wrap-ansi, strip-ansi and slice-ansi. Zero dependencies.",
+  "version": "0.1.0",
+  "description": "A printer's line gauge \u2014 the steel rule marked in picas and points. Measuring, wrapping, truncating and slicing styled terminal text without the edge fraying \u2014 grapheme-correct over Intl.Segmenter. Drop-in paths for string-width, wrap-ansi, strip-ansi and slice-ansi. Zero dependencies.",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -12,6 +12,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./wrap": {
+      "types": "./dist/wrap.d.ts",
+      "import": "./dist/wrap.js",
+      "default": "./dist/wrap.js"
     }
   },
   "files": [
@@ -49,6 +54,8 @@
     "unicode"
   ],
   "devDependencies": {
-    "vitest": "^4.0.0"
+    "string-width": "^8.1.0",
+    "vitest": "^4.0.0",
+    "wrap-ansi": "^10.0.1"
   }
 }