linegauge 0.2.0 → 0.3.0

package/README.md

@@ -100,6 +100,66 @@ text.
 scan when the string has no non-ASCII code unit, so the segmenter is reached only when it
 earns its cost.
 
+## Plugins
+
+**linegauge hosts no plugin key, and that is a decision rather than an omission.** Every
+other package in the family hosts one — `tokens` in roundel, `spinners` and `borders` and
+`glyphs` and `components` in flagstaff, `capabilities` in paratext, `sources` in seniority,
+`handlers` in closeout, `resolvers` in bellpull, `widgets` in caique. Each of those keys sits
+over a question with more than one right answer: which colour, which glyph, which terminal,
+where configuration lives, how an executable is found. A plugin settles it for one program
+without making anybody else wrong.
+
+These six functions are not that kind of question. `width('古代')` is 4 because Unicode
+classes those code points East Asian Wide and a terminal gives each of them two columns;
+`slice` returns the columns it was asked for or it returns the wrong string. A plugin key
+here would not extend what linegauge does — it would let a caller redefine what the terminal
+does, silently, for everything above it. The failure would not even surface as an error: a
+box comes out a column short, a table gains a phantom column, and nothing throws.
+
+There is a second reason, and it is the one that decides it. This package's correctness is
+differential — `width` is graded against `string-width`, `wrap` against `wrap-ansi`, `slice`
+against `slice-ansi`, `truncate` against `cli-truncate`. A registered contribution would put
+answers under the published pass rate that no grader ever saw, so the number would stop
+meaning what it says.
+
+The two things that genuinely vary are already handled without a registry:
+
+- **The Unicode data.** The Wide and Fullwidth table is Unicode's, and cluster boundaries
+  come from the platform's `Intl.Segmenter`. When Unicode ships a version the table changes —
+  that is a release of this package, re-graded, not a registration a caller can make.
+- **The environment.** How wide the terminal is, and whether there is one, are the caller's
+  to pass; nothing here reads `process`. That is a parameter, not a plugin.
+
+The family's plugin contract records this refusal next to the other layers' keys (R5a), so
+"no key" is one of the contract's answers rather than a hole in it. If a real second answer
+ever arrives — an ambiguous-width policy some terminal actually needs — it lands as an option
+with a differential test behind it, because the graders have to see it.
+
+## Benchmarks
+
+Every number here is produced by `npm run bench` and published at [/docs/benchmarks](/docs/benchmarks).
+
+Graded by the incumbent's own test suite:
+
+| suite | passing |
+| :-- | --: |
+| `slice-ansi` | 15 / 15 ¹ |
+| `string-width` | 229 / 229 |
+| `strip-ansi` | 8 / 8 |
+| `wrap-ansi` | 80 / 80 |
+
+¹ A case the incumbent marks `test.failing()` — it cannot do the thing and says so in
+its own suite — which this package passes. The runner reports that as a failure, because
+to the incumbent an unexpected pass means a stale annotation; it is counted here as the
+pass it is, and marked rather than left to look like the ones beside it.
+
+Weight, installed and tree-inclusive: **83,538 bytes** against **170,342** for the incumbents it replaces — a ratio of **0.4904**.
+## Where it sits
+
+It hosts no plugin key of its own.
+
+`burgee` and `flagstaff` build on it, and it builds on nothing in this family.
 ## Licence
 
 MIT

package/dist/index.d.ts

@@ -23,7 +23,7 @@
  * `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.
+ * R2's fast path: locked by `differential.test.ts`.
  */
 export { lineCount, measure, width, width as default, type WidthOptions } from './width.js';
 export { slice } from './slice.js';

package/dist/index.js

@@ -23,7 +23,7 @@
  * `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.
+ * R2's fast path: locked by `differential.test.ts`.
  */
 export { lineCount, measure, width, width as default } from './width.js';
 export { slice } from './slice.js';

package/dist/slice.d.ts

@@ -8,3 +8,11 @@
  * error, matching `String.prototype.slice`'s temperament if not its units.
  */
 export declare function slice(string: string, start?: number, end?: number): string;
+/**
+ * The default export, for the reason `strip.ts` gives at length: `slice-ansi`'s suite
+ * imports its entry point's **default**, and that suite now grades this file.
+ *
+ * The specifier is described rather than quoted on purpose — see the note on `wrap`'s
+ * default: `subpath-isolation.test.ts` reads the emitted text, comments and all.
+ */
+export { slice as default };

package/dist/slice.js

@@ -97,4 +97,13 @@ export function slice(string, start = 0, end = Number.POSITIVE_INFINITY) {
         return '';
     return cut.body + (cut.link === undefined ? '' : hyperlink('')) + closingSequence(cut.active);
 }
+/**
+ * The default export, for the reason `strip.ts` gives at length: `slice-ansi`'s suite
+ * imports its entry point's **default**, and that suite now grades this file.
+ *
+ * The specifier is described rather than quoted on purpose — see the note on `wrap`'s
+ * default: `subpath-isolation.test.ts` reads the emitted text, comments and all.
+ */
+// eslint-disable-next-line import-next/no-default-export -- the incumbent's own suite imports a default; see above. This is the drop-in surface, not a style choice.
+export { slice as default };
 //# sourceMappingURL=slice.js.map

package/dist/strip.d.ts

@@ -24,3 +24,21 @@
  * would have nothing left to match.
  */
 export declare function strip(string: string): string;
+/**
+ * The same function again, as the default export, because `strip-ansi`'s own suite imports
+ * a default — and that suite is now this module's grader
+ * (`compat-oracle/vendor/strip-ansi`, `baseline/strip-ansi.json`).
+ *
+ * It is a *subpath* default rather than the package's, and it has to be: R8 spends the root
+ * default on `width`, so `overrides: { "string-width": "npm:linegauge@^1" }` resolves. A
+ * `strip-ansi` façade can therefore only ever be `linegauge/strip`, and this is the line
+ * that makes `import stripAnsi from 'linegauge/strip'` read exactly like the import it
+ * replaces. `truncate` and `widest` deliberately do not have one yet: an export is a
+ * contract forever, and neither has a vendored suite holding it to the incumbent's shape.
+ *
+ * Spelled `strip as default` rather than `export default strip` to match how `index.ts`
+ * publishes `width as default`: the alias is a live binding to the same declaration, so
+ * there is exactly one `strip` in the module however it is imported — which is the property
+ * `facade-defaults.test.ts` asserts with `toBe`, not `toEqual`.
+ */
+export { strip as default };

package/dist/strip.js

@@ -59,4 +59,23 @@ export function strip(string) {
     });
     return nodeStrip(out);
 }
+/**
+ * The same function again, as the default export, because `strip-ansi`'s own suite imports
+ * a default — and that suite is now this module's grader
+ * (`compat-oracle/vendor/strip-ansi`, `baseline/strip-ansi.json`).
+ *
+ * It is a *subpath* default rather than the package's, and it has to be: R8 spends the root
+ * default on `width`, so `overrides: { "string-width": "npm:linegauge@^1" }` resolves. A
+ * `strip-ansi` façade can therefore only ever be `linegauge/strip`, and this is the line
+ * that makes `import stripAnsi from 'linegauge/strip'` read exactly like the import it
+ * replaces. `truncate` and `widest` deliberately do not have one yet: an export is a
+ * contract forever, and neither has a vendored suite holding it to the incumbent's shape.
+ *
+ * Spelled `strip as default` rather than `export default strip` to match how `index.ts`
+ * publishes `width as default`: the alias is a live binding to the same declaration, so
+ * there is exactly one `strip` in the module however it is imported — which is the property
+ * `facade-defaults.test.ts` asserts with `toBe`, not `toEqual`.
+ */
+// eslint-disable-next-line import-next/no-default-export -- the incumbent's own suite imports a default; see above. This is the drop-in surface, not a style choice.
+export { strip as default };
 //# sourceMappingURL=strip.js.map

package/dist/style.js

@@ -249,7 +249,18 @@ export function applyToken(token, active) {
         const family = `modifier-${token.code}`;
         removeFamily(active, family);
         active.push({ family, open: token.open, close });
+        return;
     }
+    // An SGR parameter this file has no close code for — `ESC[20m`, `ESC[1001m`. It used to
+    // be dropped here, which is the one failure on the `slice-ansi` row that was ours
+    // (`design.md` § R10 category E): the text survived a cut and its style did not, silently.
+    // The sequence is the caller's, not this library's to vet, so it is carried through and
+    // reopened like any other style. `SGR_RESET` is its closer because it is the only one
+    // that is correct for a parameter whose meaning is unknown — there is nothing to derive a
+    // narrower close from — and it is what `slice-ansi` emits for the same input.
+    const family = `unknown-${token.open}`;
+    removeFamily(active, family);
+    active.push({ family, open: token.open, close: SGR_RESET });
 }
 export const applyParameters = (parameters, active) => {
     for (const token of sgrTokens(parameters))

package/dist/width.js

@@ -131,24 +131,154 @@ function isWide(codePoint) {
 function isAmbiguous(codePoint) {
     return inTable(AMBIGUOUS, codePoint);
 }
-// `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;
+/**
+ * `v`-mode properties: the whole point of using them is that Node ships the tables.
+ *
+ * The mark classes are spelled out as `Nonspacing_Mark` and `Enclosing_Mark` rather than
+ * the `\p{Mark}` that stood here, because `\p{Mark}` is those two **and** `Spacing_Mark` —
+ * and a spacing mark is exactly the kind that does occupy a column. `ा`, Devanagari
+ * vowel sign AA, answered 0 under the wider class and a terminal draws it one column wide.
+ *
+ * `\p{Format}` joins the zero-width class for the mirror-image reason. A prepended
+ * concatenation mark — `U+0600`, `U+06DD`, `U+070F` — is `Format` but *not*
+ * `Default_Ignorable`, so it fell through to the base-scalar path below, which stripped it
+ * as leading non-printing, found an empty remainder, read code point 0 and charged a column
+ * for it. Charging a column for a character the cursor never advances past is the shape of
+ * bug that stays invisible until a box comes out a column short.
+ */
+const ZERO_WIDTH_CLUSTER = /^(?:\p{Default_Ignorable_Code_Point}|\p{Control}|\p{Format}|\p{Nonspacing_Mark}|\p{Enclosing_Mark}|\p{Surrogate})+$/v;
+const LEADING_NON_PRINTING = /^[\p{Default_Ignorable_Code_Point}\p{Control}\p{Format}\p{Nonspacing_Mark}\p{Enclosing_Mark}\p{Surrogate}]+/v;
 const RGI_EMOJI = /^\p{RGI_Emoji}$/v;
+const SPACING_MARK = /^\p{Spacing_Mark}$/v;
+const EXTENDED_PICTOGRAPHIC = /^\p{Extended_Pictographic}$/u;
+/**
+ * An **unqualified keycap**: the base, then `U+20E3`, with the `U+FE0F` that would have made
+ * it fully qualified missing. The base class is explicit — a digit, `#` or `*` — because
+ * `U+260E U+FE0F U+20E3` is *not* a keycap, and `string-width`'s suite grades that too.
+ */
+const UNQUALIFIED_KEYCAP = /^[\d#*]\u20E3$/u;
+const ZWJ = '\u200D';
+/** Two pictographs is what separates an emoji ZWJ sequence from an Indic conjunct. */
+const EMOJI_ZWJ_PICTOGRAPHS = 2;
+/**
+ * Longest cluster worth testing for an emoji sequence. Real ones run well under thirty code
+ * units; the cap is here so a pathological cluster cannot turn a width call into a scan.
+ */
+const EMOJI_SCAN_LIMIT = 50;
 /** The Halfwidth and Fullwidth Forms block, which a cluster can carry after its base. */
 const FORMS_FIRST = 0xff00;
 const FORMS_LAST = 0xffef;
+/**
+ * Conjoining jamo, in the three classes modern Hangul composes from: leading (L), vowel (V)
+ * and trailing (T). Each has an archaic extension block beside the main one.
+ */
+const JAMO_LEADING = [0x1100, 0x115f, 0xa960, 0xa97c];
+const JAMO_VOWEL = [0x1160, 0x11a7, 0xd7b0, 0xd7c6];
+const JAMO_TRAILING = [0x11a8, 0x11ff, 0xd7cb, 0xd7fb];
 const segmenter = new Intl.Segmenter();
-/** Columns a cluster's trailing fullwidth forms add — `ｶﾞ` is a base plus a wide mark. */
-function trailingForms(cluster) {
+/** East Asian Width of one code point, in columns, under the caller's ambiguous policy. */
+function columnsOf(codePoint, ambiguousIsWide) {
+    return isWide(codePoint) || (ambiguousIsWide && isAmbiguous(codePoint)) ? WIDE_COLUMNS : NARROW;
+}
+/**
+ * Columns a cluster's trailing **spacing marks and fullwidth forms** add. `ｶﾞ` is a base
+ * plus a wide mark; `क` + `ा` is a base plus a spacing mark. Both advance the cursor past
+ * the base, and neither is a separate cluster, so neither can be counted anywhere else.
+ *
+ * The walk is over the *visible* cluster — what is left after the leading non-printing run
+ * has been removed — so that the character being skipped as "the base" is the base, not a
+ * format character standing in front of it.
+ */
+function trailingColumns(visible, ambiguousIsWide) {
     let extra = 0;
-    for (const character of [...cluster].slice(1)) {
+    for (const character of [...visible].slice(1)) {
         const codePoint = character.codePointAt(0) ?? 0;
-        if (codePoint >= FORMS_FIRST && codePoint <= FORMS_LAST)
-            extra += isWide(codePoint) ? WIDE_COLUMNS : NARROW;
+        const isForm = codePoint >= FORMS_FIRST && codePoint <= FORMS_LAST;
+        if (isForm || SPACING_MARK.test(character))
+            extra += columnsOf(codePoint, ambiguousIsWide);
     }
     return extra;
 }
+/**
+ * Whether a cluster is an emoji sequence that `\p{RGI_Emoji}` refuses because it is
+ * **minimally qualified or unqualified** — the same sequence with its `U+FE0F` left off.
+ * A terminal renders `U+2764 ZWJ U+1F525` as one two-column emoji whether or not the
+ * variation selector is there; the regex only matches the fully-qualified spelling.
+ *
+ * Two shapes, and both need their guard. A ZWJ sequence counts only when **two or more**
+ * pictographs are joined, which is what keeps `क् ZWJ ष` — an Indic conjunct using the same
+ * joiner — one column. A keycap counts only over a digit, `#` or `*`, which is what keeps
+ * the invalid `U+260E U+FE0F U+20E3` one column. Both of those are cases in the suite that
+ * grades this file, and both passed before this function existed.
+ */
+function isUnqualifiedEmojiSequence(cluster) {
+    if (cluster.length > EMOJI_SCAN_LIMIT)
+        return false;
+    if (UNQUALIFIED_KEYCAP.test(cluster))
+        return true;
+    if (!cluster.includes(ZWJ))
+        return false;
+    let pictographs = 0;
+    for (const character of cluster) {
+        if (EXTENDED_PICTOGRAPHIC.test(character))
+            pictographs += 1;
+        if (pictographs >= EMOJI_ZWJ_PICTOGRAPHS)
+            return true;
+    }
+    return false;
+}
+/** Whether `codePoint` falls in one of a flat `[low, high]` pair list. */
+function inPairs(pairs, codePoint) {
+    for (let i = 0; i < pairs.length; i += PAIR) {
+        if (codePoint >= (pairs[i] ?? 0) && codePoint <= (pairs[i + 1] ?? 0))
+            return true;
+    }
+    return false;
+}
+function isJamo(codePoint) {
+    return inPairs(JAMO_LEADING, codePoint) || inPairs(JAMO_VOWEL, codePoint) || inPairs(JAMO_TRAILING, codePoint);
+}
+/**
+ * Columns a cluster of **conjoining Hangul jamo** occupies, or `undefined` when the cluster
+ * does not start with one — in which case the caller's ordinary base-scalar path is right.
+ *
+ * This is the one category that needs a walk rather than a table lookup. `Intl.Segmenter`
+ * joins a whole run of jamo into a single grapheme cluster (GB6, GB7, GB8), so measuring the
+ * cluster by its first code point answered **2** for a six-jamo run a terminal draws **12**
+ * columns wide. Modern Hangul composes L + V, or L + V + T, into one syllable block two
+ * columns wide; jamo that find no partner stay additive at their own East Asian Width, which
+ * makes a leading jamo 2 and a vowel or trailing jamo 1.
+ *
+ * A cluster that begins with jamo and then turns into something else — a leading jamo
+ * followed by a precomposed syllable — measures the jamo by this rule and the remainder by
+ * East Asian Width, which is how `U+1100 U+AC00` comes to 4 rather than 2.
+ */
+function hangulColumns(visible, ambiguousIsWide) {
+    const codePoints = [];
+    for (const character of visible) {
+        if (ZERO_WIDTH_CLUSTER.test(character))
+            continue;
+        codePoints.push(character.codePointAt(0) ?? 0);
+    }
+    if (codePoints.length === 0 || !isJamo(codePoints[0] ?? 0))
+        return undefined;
+    let columns = 0;
+    for (let index = 0; index < codePoints.length; index += 1) {
+        const codePoint = codePoints[index] ?? 0;
+        if (!isJamo(codePoint)) {
+            for (let rest = index; rest < codePoints.length; rest += 1)
+                columns += columnsOf(codePoints[rest] ?? 0, ambiguousIsWide);
+            return columns;
+        }
+        if (inPairs(JAMO_LEADING, codePoint) && inPairs(JAMO_VOWEL, codePoints[index + 1] ?? -1)) {
+            columns += WIDE_COLUMNS;
+            index += inPairs(JAMO_TRAILING, codePoints[index + PAIR] ?? -1) ? PAIR : 1;
+            continue;
+        }
+        columns += columnsOf(codePoint, ambiguousIsWide);
+    }
+    return columns;
+}
 /**
  * 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
@@ -159,14 +289,18 @@ export function measure(text, ambiguousIsWide = false) {
     for (const { segment } of segmenter.segment(text)) {
         if (ZERO_WIDTH_CLUSTER.test(segment))
             continue;
-        if (RGI_EMOJI.test(segment)) {
+        if (RGI_EMOJI.test(segment) || isUnqualifiedEmojiSequence(segment)) {
             columns += WIDE_COLUMNS;
             continue;
         }
-        const codePoint = segment.replace(LEADING_NON_PRINTING, '').codePointAt(0) ?? 0;
-        const wide = isWide(codePoint) || (ambiguousIsWide && isAmbiguous(codePoint));
-        columns += wide ? WIDE_COLUMNS : NARROW;
-        columns += trailingForms(segment);
+        const visible = segment.replace(LEADING_NON_PRINTING, '');
+        const hangul = hangulColumns(visible, ambiguousIsWide);
+        if (hangul !== undefined) {
+            columns += hangul;
+            continue;
+        }
+        columns += columnsOf(visible.codePointAt(0) ?? 0, ambiguousIsWide);
+        columns += trailingColumns(visible, ambiguousIsWide);
     }
     return columns;
 }

package/dist/wrap.d.ts

@@ -10,3 +10,13 @@ export interface WrapOptions {
 }
 /** Wrap `string` to `columns`, keeping its ANSI intact and each row self-contained. */
 export declare function wrap(string: string, columns: number, options?: WrapOptions): string;
+/**
+ * The default export, for the reason `strip.ts` gives at length: `wrap-ansi` 10's suite
+ * imports its entry point's **default**, and that suite now grades this file.
+ *
+ * Written without quoting the specifier, deliberately. `subpath-isolation.test.ts` scans the
+ * *emitted text* of `dist/wrap.js` for relative imports, comments included, so a doc comment
+ * that spells one out makes the entry look as though it reaches a sibling. Caught by that
+ * lock on 2026-09-14, which is the lock doing exactly its job on the wrong input.
+ */
+export { wrap as default };

package/dist/wrap.js

@@ -268,4 +268,15 @@ export function wrap(string, columns, options = {}) {
         .map((line) => wrapLine(expandTabs(line), columns, options))
         .join('\n');
 }
+/**
+ * The default export, for the reason `strip.ts` gives at length: `wrap-ansi` 10's suite
+ * imports its entry point's **default**, and that suite now grades this file.
+ *
+ * Written without quoting the specifier, deliberately. `subpath-isolation.test.ts` scans the
+ * *emitted text* of `dist/wrap.js` for relative imports, comments included, so a doc comment
+ * that spells one out makes the entry look as though it reaches a sibling. Caught by that
+ * lock on 2026-09-14, which is the lock doing exactly its job on the wrong input.
+ */
+// eslint-disable-next-line import-next/no-default-export -- the incumbent's own suite imports a default; see above. This is the drop-in surface, not a style choice.
+export { wrap as default };
 //# sourceMappingURL=wrap.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linegauge",
-  "version": "0.2.0",
+  "version": "0.3.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",