linegauge 0.1.0 → 0.2.0

package/README.md

@@ -1,28 +1,104 @@
 # linegauge
 
-**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.
-
-That is this package's whole job. Width, wrap, truncate and slice are one problem wearing four names: **cutting styled text without letting the edge come apart** — no dangling escape sequence, no half a grapheme, no severed emoji cluster.
-
-## What it will be
-
-- **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.
-- **Zero external dependencies.**
+**Measuring, wrapping, truncating and slicing styled terminal text — without the edge
+fraying.**
+
+A printer's line gauge is the steel rule marked in picas and points: a compositor holds it
+against a line of type and checks it fits the measure it was set to.
+
+Zero dependencies. Grapheme-correct over the platform's own `Intl.Segmenter`.
+
+```bash
+npm i linegauge
+```
+
+## One problem wearing five names
+
+`width` · `wrap` · `truncate` · `slice` · `widest`
+
+They look like five utilities. They are one: **cutting styled text without letting the edge
+come apart** — no dangling escape sequence, no half a grapheme, no severed emoji cluster.
+Each has to know where the ANSI is and where the cluster boundaries are, and once you know
+that, you may as well answer all five.
+
+The ecosystem splits it across twelve packages — `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` — which
+between them sit under most of the terminal ecosystem.
+
+## Use
+
+```js
+import { width, wrap, truncate, slice, widest } from 'linegauge';
+
+width('古代'); // 4 — East Asian wide, two columns each
+width('👨‍👩‍👧‍👦'); // 2 — one cluster, not four people
+
+wrap('a long sentence that needs folding', 12);
+truncate('the quick brown fox', 10); // 'the quick…'
+slice(styled, 2, 4); // columns 2 and 3, styles intact
+widest(['a', 'bbb', 'cc']); // 3
+```
+
+### The default export is `string-width`
+
+Byte-for-byte call-compatible, so this resolves without a code change:
+
+```json
+{ "overrides": { "string-width": "npm:linegauge@^0.2" } }
+```
+
+## What "without the edge fraying" means
+
+**A cluster is atomic.** A cut that would land inside a grapheme drops the whole cluster
+rather than half of it. Half an emoji is not a narrower emoji, it is mojibake, and a flag
+cut down the middle is two unrelated regional-indicator letters.
+
+**A style that was open stays open — and gets closed.** A cut re-emits the styles active at
+its start and closes them at its end, so the result is self-contained: paste it anywhere and
+it neither loses its colour nor leaks it into what follows.
+
+**The ellipsis is inside the budget, not on top of it.** `truncate(text, 10)` occupies ten
+columns or fewer, never eleven. That is the property a table column depends on, and getting
+it wrong is how a layout gains a phantom column under one input.
+
+**`widest` takes lines, not a blob.** It accepts any iterable of strings, so the caller says
+where the boundaries are rather than having a newline convention assumed for them.
+
+## Graded by the packages it replaces
+
+The incumbent is the specification. `width` runs against `string-width`, `wrap` against
+`wrap-ansi`, `slice` against `slice-ansi` and `truncate` against `cli-truncate`.
+
+## API
+
+| | |
+| :-- | :-- |
+| `width(text, { countAnsiEscapeCodes })` | terminal columns the text occupies |
+| `wrap(text, columns, options)` | fold to a width, styles preserved across rows |
+| `truncate(text, columns, { position, ellipsis })` | cut to a budget, ellipsis counted inside it |
+| `slice(text, start, end)` | the columns `[start, end)`, self-contained |
+| `widest(lines)` | the width of the widest line of any iterable |
+| `lineCount(text, columns)` | rows the text occupies at that width |
+| `measure(text)` | columns of plain text, no escape scan |
+
+Non-strings answer `0` rather than throwing, because a width function is usually reached
+with whatever a template produced.
+
+## Design notes
+
+**Ambiguous-width characters count narrow**, which is what a terminal does unless told it is
+rendering an East Asian locale. `string-width` makes that an option; nothing above this has
+ever needed the other answer, so it is not one here.
+
+**Not a terminal emulator.** Semicolon-delimited SGR, colon-delimited extended colour and
+OSC 8 hyperlinks 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.
+
+**Still at the Design→Build gate:** an exported `strip`, and the ASCII fast path — a byte
+scan when the string has no non-ASCII code unit, so the segmenter is reached only when it
+earns its cost.
 
 ## Licence
 

package/dist/index.d.ts

@@ -15,10 +15,19 @@
  * 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.
+ * `slice`, `truncate` and `widest` came next, built on the style stack `wrap` already
+ * carried — which is the consolidation the design is named for: `slice-ansi`, `wrap-ansi`
+ * and `cli-truncate` each keep their own copy of it, and they disagree at the edges.
+ *
+ * `strip` (R3) followed, and it is where the measured divergence from Node's own
+ * `stripVTControlCharacters` is recorded — one shape in sixteen, and it was a live bug in
+ * `width()`.
+ *
+ * Still at the Design→Build gate: the R2 ASCII fast path.
  */
-export { lineCount, measure, width, width as default } from './width.js';
+export { lineCount, measure, width, width as default, type WidthOptions } from './width.js';
+export { slice } from './slice.js';
+export { strip } from './strip.js';
+export { truncate, type TruncateOptions } from './truncate.js';
+export { widest } from './widest.js';
 export { wrap, type WrapOptions } from './wrap.js';

package/dist/index.js

@@ -15,11 +15,20 @@
  * 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.
+ * `slice`, `truncate` and `widest` came next, built on the style stack `wrap` already
+ * carried — which is the consolidation the design is named for: `slice-ansi`, `wrap-ansi`
+ * and `cli-truncate` each keep their own copy of it, and they disagree at the edges.
+ *
+ * `strip` (R3) followed, and it is where the measured divergence from Node's own
+ * `stripVTControlCharacters` is recorded — one shape in sixteen, and it was a live bug in
+ * `width()`.
+ *
+ * Still at the Design→Build gate: the R2 ASCII fast path.
  */
 export { lineCount, measure, width, width as default } from './width.js';
+export { slice } from './slice.js';
+export { strip } from './strip.js';
+export { truncate } from './truncate.js';
+export { widest } from './widest.js';
 export { wrap } from './wrap.js';
 //# sourceMappingURL=index.js.map

package/dist/slice.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+/**
+ * `[start, end)` in display columns. A negative or reversed range is empty rather than an
+ * error, matching `String.prototype.slice`'s temperament if not its units.
+ */
+export declare function slice(string: string, start?: number, end?: number): string;

package/dist/slice.js

@@ -0,0 +1,100 @@
+/**
+ * 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.
+ */
+/**
+ * R4 — cut a styled string in **display columns**, never in code units.
+ *
+ * `"\u001B[31mred\u001B[39m".slice(0, 3)` returns three characters of an escape sequence
+ * and no red at all; that is the bug this exists to remove, and it is the same bug in every
+ * hand-rolled column-cutter. Three rules, none of which a code-unit slice can honour:
+ *
+ *   1. **Never split a grapheme cluster.** A cluster that straddles a boundary is included
+ *      whole — the cut rounds *outward*, never inward, so a slice can be one column wider
+ *      than asked but never returns half a family emoji.
+ *   2. **Close what is open at the cut, and reopen it at the start.** A style opened before
+ *      `start` is re-emitted at the front of the result, because the caller is going to
+ *      print this fragment somewhere the opener never reached.
+ *   3. **A hyperlink is a style too** (`OSC 8`), closed and reopened the same way.
+ *
+ * Built on the same stack `wrap` uses rather than a second copy of it, which is the whole
+ * consolidation: `slice-ansi` and `wrap-ansi` each carry their own, and they disagree.
+ */
+import { applyParameters, closingSequence, hyperlink, matchEscape, openingSequence, segmenter } from './style.js';
+import { measure } from './width.js';
+/**
+ * Rule 2. Deliberately without `wrap`'s `applyLeadingResets`: that optimisation drops a
+ * style whose reset immediately follows the cut, which is right for a row boundary and
+ * wrong here — by the time the first kept cluster is known the walk has already run past
+ * the whole plain-text segment, so the "next" sequence it would inspect belongs to text
+ * this slice still contains. Reopening a style that is about to be reset costs bytes;
+ * dropping one that is not costs the colour.
+ */
+function open(cut) {
+    if (cut.started)
+        return;
+    cut.started = true;
+    cut.body += openingSequence(cut.active);
+    if (cut.link !== undefined)
+        cut.body += hyperlink(cut.link.uri, cut.link.parameters);
+}
+/**
+ * An escape sequence: it always moves the stack, and is copied through only when the cut
+ * has started and has not finished. The stack is what gets re-emitted at `start`, which is
+ * why a sequence outside the range is still read.
+ */
+function takeEscape(cut, escape, end) {
+    const groups = escape.groups ?? {};
+    if (groups['sgr'] !== undefined)
+        applyParameters(groups['sgr'], cut.active);
+    else if (groups['uri'] !== undefined)
+        cut.link = groups['uri'].length === 0 ? undefined : { parameters: groups['parameters'] ?? '', uri: groups['uri'] };
+    if (cut.started && cut.column < end)
+        cut.body += escape[0];
+}
+/** One run of plain text, cluster by cluster. Returns true when the range has been filled. */
+function takeText(cut, run, start, end) {
+    for (const { segment } of segmenter.segment(run)) {
+        const columns = measure(segment);
+        // Rule 1: a cluster is in when any column it occupies is in, so a zero-width mark rides
+        // with the cluster it follows rather than falling off the front of a slice.
+        if (cut.column + Math.max(columns, 1) > start && cut.column < end) {
+            open(cut);
+            cut.body += segment;
+        }
+        cut.column += columns;
+        if (cut.column >= end && columns > 0)
+            return true;
+    }
+    return cut.column >= end;
+}
+/**
+ * `[start, end)` in display columns. A negative or reversed range is empty rather than an
+ * error, matching `String.prototype.slice`'s temperament if not its units.
+ */
+export function slice(string, start = 0, end = Number.POSITIVE_INFINITY) {
+    if (end <= start || string.length === 0)
+        return '';
+    const cut = { active: [], link: undefined, column: 0, body: '', started: false };
+    let index = 0;
+    while (index < string.length) {
+        const escape = matchEscape(string, index);
+        if (escape !== undefined) {
+            takeEscape(cut, escape, end);
+            index += escape[0].length;
+            continue;
+        }
+        let run = '';
+        while (index < string.length && matchEscape(string, index) === undefined) {
+            run += string[index];
+            index += 1;
+        }
+        if (takeText(cut, run, start, end))
+            break;
+    }
+    if (!cut.started)
+        return '';
+    return cut.body + (cut.link === undefined ? '' : hyperlink('')) + closingSequence(cut.active);
+}
+//# sourceMappingURL=slice.js.map

package/dist/strip.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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.
+ */
+/**
+ * Everything a terminal would print, with the escape sequences removed: CSI (SGR and the
+ * cursor and erase forms), OSC including `OSC 8` hyperlinks under both terminators, DCS, the
+ * charset selections, and the single-character escapes. A lone `ESC` with nothing that parses
+ * after it is text and is kept — the same answer `strip-ansi` gives.
+ *
+ * Two passes, which is the design's prescription taken literally: *"using
+ * `util.stripVTControlCharacters` where it is exact and a local scan where it is not."*
+ *
+ *   1. The local scan, over `style.ts`'s `ANSI_ESCAPE`. It removes CSI and OSC **including
+ *      the colon form** of an extended colour, which is the one shape Node gets wrong.
+ *   2. Node's stripper on what is left — the single-character escapes (`ESC c`), the charset
+ *      selections (`ESC ( B`) and a truncated sequence at the end of a string. `ANSI_ESCAPE`
+ *      matches none of those, because `wrap` never needed them: it was built to find the
+ *      sequences it has to *reopen*, and a charset selection is not one.
+ *
+ * Order is load-bearing. Ours runs first so the colon form is already gone by the time Node
+ * sees the string; reversed, pass 2 would leave `:2::255:0:0m` behind as text and pass 1
+ * would have nothing left to match.
+ */
+export declare function strip(string: string): string;

package/dist/strip.js

@@ -0,0 +1,62 @@
+/**
+ * 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.
+ */
+/**
+ * R3 — remove the sequences a terminal consumes, and leave the text it prints.
+ *
+ * The design says to use `util.stripVTControlCharacters` "where it is exact and a local scan
+ * where it is not — measured, and the divergence recorded rather than assumed". Measured, on
+ * Node 24 over sixteen sequence shapes: **fifteen agree with `strip-ansi` and one does not.**
+ *
+ *   ESC[38:2::255:0:0m   node -> ":2::255:0:0m"     strip-ansi -> ""
+ *
+ * That is the colon form of an extended colour (ITU T.416, which `chalk`, `wrap-ansi` and
+ * every 24-bit-colour library emit): Node's scanner stops at the first `:` and leaves the
+ * rest of the sequence in the output as text. One shape, and the one that matters most,
+ * because it is **not** a rare dialect — it is how a truecolor SGR is written when the
+ * sub-parameter form is used.
+ *
+ * It was a live bug here, not a theoretical one. `width.ts` called
+ * `stripVTControlCharacters`, so `width("ESC[38:2::255:0:0mred ESC[39m")` answered **15**
+ * where `string-width` answers **3** — and every caller that measures went with it: `wrap`,
+ * `slice`, `truncate`, `widest`, and in `flagstaff` the box, the table and the spinner.
+ *
+ * So the local scan is the whole implementation, over `style.ts`'s `ANSI_ESCAPE` — which has
+ * always handled the colon form, because `wrap` needs to reopen those colours across a row.
+ * The package understood the syntax in one module and mis-stripped it in another, which is
+ * precisely the duplication the consolidation exists to remove.
+ */
+import { stripVTControlCharacters as nodeStrip } from 'node:util';
+import { forEachSegment } from './style.js';
+/**
+ * Everything a terminal would print, with the escape sequences removed: CSI (SGR and the
+ * cursor and erase forms), OSC including `OSC 8` hyperlinks under both terminators, DCS, the
+ * charset selections, and the single-character escapes. A lone `ESC` with nothing that parses
+ * after it is text and is kept — the same answer `strip-ansi` gives.
+ *
+ * Two passes, which is the design's prescription taken literally: *"using
+ * `util.stripVTControlCharacters` where it is exact and a local scan where it is not."*
+ *
+ *   1. The local scan, over `style.ts`'s `ANSI_ESCAPE`. It removes CSI and OSC **including
+ *      the colon form** of an extended colour, which is the one shape Node gets wrong.
+ *   2. Node's stripper on what is left — the single-character escapes (`ESC c`), the charset
+ *      selections (`ESC ( B`) and a truncated sequence at the end of a string. `ANSI_ESCAPE`
+ *      matches none of those, because `wrap` never needed them: it was built to find the
+ *      sequences it has to *reopen*, and a charset selection is not one.
+ *
+ * Order is load-bearing. Ours runs first so the colon form is already gone by the time Node
+ * sees the string; reversed, pass 2 would leave `:2::255:0:0m` behind as text and pass 1
+ * would have nothing left to match.
+ */
+export function strip(string) {
+    if (string === '')
+        return '';
+    let out = '';
+    forEachSegment(string, (text) => {
+        out += text;
+    });
+    return nodeStrip(out);
+}
+//# sourceMappingURL=strip.js.map

package/dist/style.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 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.
+ */
+/**
+ * The style stack — the part of this package that every cutting operation shares.
+ *
+ * `wrap`, `slice` and `truncate` are one algorithm wearing three names: walk the string,
+ * keep a stack of the SGR parameters a terminal currently has open, emit graphemes while
+ * inside the range you were asked for, and at every cut emit the closer for whatever is
+ * open and re-emit the openers on resume. The twelve incumbents write that three times
+ * between them — `wrap-ansi`, `slice-ansi` and `cli-truncate` each carry their own copy —
+ * and disagree at the edges, which is most of the reason this package exists.
+ *
+ * Extracted from `wrap.ts` when `slice` arrived, with wrap-ansi's own suite as the check:
+ * this module is a move, and `wrap.test.ts` grades every case against the real `wrap-ansi`,
+ * so a mistake in the extraction is a red suite rather than a subtle divergence.
+ *
+ * It is not a published subpath. `linegauge/wrap` and `linegauge/slice` each reach it, and
+ * R8 keeps them from reaching each other.
+ */
+export declare const ESC = "\u001B";
+export declare const BELL = "\u0007";
+export declare const CSI = "[";
+export declare const OSC = "]";
+export declare const SGR_TERMINATOR = "m";
+/** How many columns a tab advances to the next stop. */
+export declare const TAB_SIZE = 8;
+export declare const ESCAPES: Set<string>;
+export declare const ANSI_ESCAPE: RegExp;
+export declare const ROW_BOUNDARY: RegExp;
+/** Every printable ASCII character is its own cluster of width one — skip the segmenter. */
+export declare const ASCII_PRINTABLE: RegExp;
+/**
+ * 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.
+ */
+export declare const MODIFIER_CLOSE: Map<number, number>;
+export declare const MODIFIER_CLOSE_CODES: Set<number>;
+export declare const segmenter: Intl.Segmenter;
+export declare const sgr: (code: number | string) => string;
+export declare const hyperlink: (url: string, parameters?: string) => string;
+/** The complete escape sequence starting at `index`, or nothing when none starts there. */
+export declare function matchEscape(string: string, index: number): RegExpExecArray | 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.
+ */
+export declare function forEachSegment(string: string, onPlainText: (text: string) => void, onEscape?: (escape: string) => void): void;
+export interface SgrToken {
+    code: number;
+    open: string;
+    hasArguments: boolean;
+}
+export interface ActiveStyle {
+    /** One slot per thing a terminal tracks separately, so a second red replaces the first. */
+    family: string;
+    open: string;
+    close: number;
+}
+export declare function sgrTokens(parameters: string): SgrToken[];
+export declare function applyToken(token: SgrToken, active: ActiveStyle[]): void;
+export declare const applyParameters: (parameters: string, active: ActiveStyle[]) => void;
+/** A row that opens with its own resets should not have them undone by the reopening. */
+export declare function applyLeadingResets(string: string, startIndex: number, active: ActiveStyle[]): void;
+export declare const closingSequence: (active: ActiveStyle[]) => string;
+export declare const openingSequence: (active: ActiveStyle[]) => string;