functionalscript 0.43.1 → 0.45.0

package/fjs/text/ascii/proof.f.mjs

@@ -0,0 +1,48 @@
+import { hexDigitCodePoint, hexDigitValue, one, range } from './module.f.mjs'
+import { stringify as jsonStringify } from '../../media/json/module.f.mjs'
+import { sort } from '../../types/object/module.f.mjs'
+import { assertEq } from '../../asserts/module.f.mjs'
+
+const stringify = jsonStringify(sort)
+
+const values = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]
+
+export const proof = {
+    range: () => {
+        const r = stringify(range("A"))
+        assertEq(r, '[65,65]')
+    },
+    hexDigitValue: {
+        digit: () => {
+            assertEq(hexDigitValue(one('0')), 0)
+            assertEq(hexDigitValue(one('9')), 9)
+        },
+        latinSmallLetterAF: () => {
+            assertEq(hexDigitValue(one('a')), 10)
+            assertEq(hexDigitValue(one('f')), 15)
+        },
+        latinCapitalLetterAF: () => {
+            assertEq(hexDigitValue(one('A')), 10)
+            assertEq(hexDigitValue(one('F')), 15)
+        },
+        notAHexDigit: () => {
+            assertEq(hexDigitValue(one('/')), null)
+            assertEq(hexDigitValue(one(':')), null)
+            assertEq(hexDigitValue(one('@')), null)
+            assertEq(hexDigitValue(one('G')), null)
+            assertEq(hexDigitValue(one('`')), null)
+            assertEq(hexDigitValue(one('g')), null)
+        },
+    },
+    hexDigitCodePoint: {
+        lowercaseDigits: () => {
+            assertEq(String.fromCodePoint(...values.map(v => hexDigitCodePoint(v))), '0123456789abcdef')
+        },
+        roundTrip: () => {
+            assertEq(stringify(values.map(v => hexDigitValue(hexDigitCodePoint(v)))), stringify(values))
+        },
+    },
+    throw: {
+        oneThrowsOnEmpty: () => one(''),
+    },
+}

package/fjs/text/code_point/module.f.d.mts

@@ -0,0 +1,92 @@
+/**
+ * Shared Unicode code-point contract for the UTF-8 and UTF-16 decoders: the
+ * error-tag mask used to flag invalid sequences, the streaming `decoder`
+ * factory that wraps a per-unit step and an end-of-input step into a single
+ * `List`-to-`List` conversion, the `eofFlush` factory that builds that
+ * end-of-input step, and the code-point classification predicates (BMP /
+ * surrogate / supplementary-plane / overall validity) that both codecs share.
+ *
+ * @module
+ *
+ * @import { List } from '../../types/list/types.ts'
+ * @import { StateScan } from '../../types/function/operator/types.ts'
+ */
+import type { List } from '../../types/list/types.ts';
+import type { StateScan } from '../../types/function/operator/types.ts';
+/**
+ * Error mask used to tag invalid code points or encoding errors. A decoded
+ * value with this bit set represents a malformed unit rather than a valid
+ * code point.
+ */
+export declare const errorMask = 2147483648;
+/**
+ * Builds a streaming decoder from the two direction-specific steps.
+ *
+ * Decoding starts from the empty (`null`) state. The input is processed unit by
+ * unit through `byteOp`, then a trailing end-of-input marker drives `eofOp` to
+ * flush any leftover decoding state.
+ *
+ * @template Unit
+ * @template S
+ * @template Cp
+ * @param {StateScan<Unit, S | null, List<Cp>>} byteOp - The per-unit decoding step.
+ * @param {(state: S | null) => readonly [List<Cp>, S | null]} eofOp - The end-of-input step that flushes the remaining state.
+ * @returns {(input: List<Unit>) => List<Cp>} A function converting a list of code units into a list of code points.
+ */
+export declare const decoder: <Unit, S, Cp>(byteOp: StateScan<Unit, S | null, List<Cp>>, eofOp: (state: S | null) => readonly [List<Cp>, S | null]) => (input: List<Unit>) => List<Cp>;
+/**
+ * Builds the end-of-input step {@link decoder} needs, from the one function
+ * that differs between codecs.
+ *
+ * The flush contract is the same for every decoder: leftover state at the end
+ * of the input becomes **exactly one** error unit and the state resets to
+ * empty (`null`); with no leftover state nothing is emitted. Only the mapping
+ * from a non-empty state to its error unit is codec-specific.
+ *
+ * @template S
+ * @template Cp
+ * @param {(state: S) => Cp} toError - Turns a non-empty leftover state into a single error unit.
+ * @returns {(state: S | null) => readonly [List<Cp>, S | null]} The end-of-input step.
+ */
+export declare const eofFlush: <S, Cp>(toError: (state: S) => Cp) => (state: S | null) => readonly [List<Cp>, S | null];
+/**
+ * Checks whether the 16-bit word (U16) is a high surrogate.
+ * Range: 0xD800 - 0xDBFF.
+ */
+export declare const isHighSurrogate: (i: number) => boolean;
+/**
+ * Checks whether the 16-bit word (U16) is a low surrogate.
+ * Range: 0xDC00 - 0xDFFF.
+ */
+export declare const isLowSurrogate: (i: number) => boolean;
+/**
+ * Checks whether the code point is in the BMP range.
+ * BMP is the main Unicode plane that covers code points 0x0000 - 0xFFFF, except
+ * for the range of surrogates.
+ *
+ * @type {(codePoint: number) => boolean}
+ */
+export declare const isBmpCodePoint: (codePoint: number) => boolean;
+/**
+ * Checks whether the code point belongs to a supplementary (additional) Unicode
+ * plane. Supplementary planes cover code points from 0x010000 to 0x10FFFF.
+ */
+export declare const isSupplementaryPlane: (i: number) => boolean;
+/**
+ * Checks whether the code point is a valid scalar value: within the assignable
+ * Unicode range (0x0000 - 0x10FFFF) and not a surrogate.
+ *
+ * @type {(c: number) => boolean}
+ */
+export declare const isValidCodePoint: (c: number) => boolean;
+/**
+ * Checks whether the code point is a *text* code point — distinct from
+ * {@link isValidCodePoint}, which gates well-formedness for decoding. A code
+ * point is text unless it is a control character: the controls are 0x0000 -
+ * 0x001F, 0x007F (DEL), and 0x0080 - 0x009F (C1), minus the whitespace block
+ * 0x0009 - 0x000D (TAB, LF, VT, FF, CR), which is legitimate in text. Every
+ * code point at or above 0x0020 that is not DEL or a C1 control is text.
+ *
+ * @type {(c: number) => boolean}
+ */
+export declare const isTextCodePoint: (c: number) => boolean;

package/fjs/text/code_point/module.f.mjs

@@ -0,0 +1,155 @@
+/**
+ * Shared Unicode code-point contract for the UTF-8 and UTF-16 decoders: the
+ * error-tag mask used to flag invalid sequences, the streaming `decoder`
+ * factory that wraps a per-unit step and an end-of-input step into a single
+ * `List`-to-`List` conversion, the `eofFlush` factory that builds that
+ * end-of-input step, and the code-point classification predicates (BMP /
+ * surrogate / supplementary-plane / overall validity) that both codecs share.
+ *
+ * @module
+ *
+ * @import { List } from '../../types/list/types.ts'
+ * @import { StateScan } from '../../types/function/operator/types.ts'
+ */
+
+import { empty, flat, stateScan } from '../../types/list/module.f.mjs'
+import { contains } from '../../types/range/module.f.mjs'
+
+//
+
+/**
+ * Error mask used to tag invalid code points or encoding errors. A decoded
+ * value with this bit set represents a malformed unit rather than a valid
+ * code point.
+ */
+export const errorMask = 0b1000_0000_0000_0000_0000_0000_0000_0000
+
+/**
+ * Builds a streaming decoder from the two direction-specific steps.
+ *
+ * Decoding starts from the empty (`null`) state. The input is processed unit by
+ * unit through `byteOp`, then a trailing end-of-input marker drives `eofOp` to
+ * flush any leftover decoding state.
+ *
+ * @template Unit
+ * @template S
+ * @template Cp
+ * @param {StateScan<Unit, S | null, List<Cp>>} byteOp - The per-unit decoding step.
+ * @param {(state: S | null) => readonly [List<Cp>, S | null]} eofOp - The end-of-input step that flushes the remaining state.
+ * @returns {(input: List<Unit>) => List<Cp>} A function converting a list of code units into a list of code points.
+ */
+export const decoder = (
+    byteOp,
+    eofOp,
+) => {
+    /** @type {StateScan<Unit | null, S | null, List<Cp>>} */
+    const op = (input, state) =>
+        input === null ? eofOp(state) : byteOp(input, state)
+    const run = stateScan(op)(null)
+    return input => flat(run(flat(/** @type {List<List<Unit|null>>} */([input, [null]]))))
+}
+
+/**
+ * Builds the end-of-input step {@link decoder} needs, from the one function
+ * that differs between codecs.
+ *
+ * The flush contract is the same for every decoder: leftover state at the end
+ * of the input becomes **exactly one** error unit and the state resets to
+ * empty (`null`); with no leftover state nothing is emitted. Only the mapping
+ * from a non-empty state to its error unit is codec-specific.
+ *
+ * @template S
+ * @template Cp
+ * @param {(state: S) => Cp} toError - Turns a non-empty leftover state into a single error unit.
+ * @returns {(state: S | null) => readonly [List<Cp>, S | null]} The end-of-input step.
+ */
+export const eofFlush = toError => state =>
+    [state === null ? empty : [toError(state)], null]
+
+/**
+ * Unicode code-point classification boundaries. The surrogate block
+ * (`0xD800`–`0xDFFF`) splits into a high half (`0xD800`–`0xDBFF`) and a low half
+ * (`0xDC00`–`0xDFFF`); the BMP ends at `0xFFFF` and `maxCodePoint` (`0x10FFFF`)
+ * is the largest assignable code point. Every predicate below is derived from
+ * these constants so the surrogate bounds and the maximum appear exactly once.
+ */
+const surrogateMin = /** @type {const} */ 0xd800
+const lowSurrogateMin = /** @type {const} */ 0xdc00
+const surrogateMax = /** @type {const} */ 0xdfff
+const bmpMax = /** @type {const} */ 0xffff
+const maxCodePoint = /** @type {const} */ 0x10_ffff
+
+/**
+ * Checks whether the 16-bit word (U16) is a high surrogate.
+ * Range: 0xD800 - 0xDBFF.
+ */
+export const isHighSurrogate = contains(surrogateMin, lowSurrogateMin - 1)
+
+/**
+ * Checks whether the 16-bit word (U16) is a low surrogate.
+ * Range: 0xDC00 - 0xDFFF.
+ */
+export const isLowSurrogate = contains(lowSurrogateMin, surrogateMax)
+
+/**
+ * Ranges of code points for the lower (Low) and higher (High) parts of the BMP
+ * (Basic Multilingual Plane), i.e. the BMP with the surrogate block removed.
+ */
+const lowBmp = contains(0x0000, surrogateMin - 1)
+const highBmp = contains(surrogateMax + 1, bmpMax)
+
+/**
+ * Checks whether the code point is in the BMP range.
+ * BMP is the main Unicode plane that covers code points 0x0000 - 0xFFFF, except
+ * for the range of surrogates.
+ *
+ * @type {(codePoint: number) => boolean}
+ */
+export const isBmpCodePoint = codePoint =>
+    lowBmp(codePoint) || highBmp(codePoint)
+
+/**
+ * Checks whether the code point belongs to a supplementary (additional) Unicode
+ * plane. Supplementary planes cover code points from 0x010000 to 0x10FFFF.
+ */
+export const isSupplementaryPlane = contains(bmpMax + 1, maxCodePoint)
+
+/**
+ * The full assignable code-point range and the surrogate block, used to gate
+ * overall validity below.
+ */
+const validRange = contains(0, maxCodePoint)
+const isSurrogate = contains(surrogateMin, surrogateMax)
+
+/**
+ * Checks whether the code point is a valid scalar value: within the assignable
+ * Unicode range (0x0000 - 0x10FFFF) and not a surrogate.
+ *
+ * @type {(c: number) => boolean}
+ */
+export const isValidCodePoint = c =>
+    validRange(c) && !isSurrogate(c)
+
+/**
+ * The control-character blocks and the whitespace exception used to separate
+ * *text* code points from binary control bytes. C0 controls span 0x0000 -
+ * 0x001F; 0x007F (DEL) and the C1 controls (0x0080 - 0x009F) form one
+ * contiguous run; the whitespace block 0x0009 - 0x000D (TAB, LF, VT, FF, CR) is
+ * the only control range legitimate in text.
+ */
+const c0Control = contains(0x00, 0x1f)
+const delAndC1Control = contains(0x7f, 0x9f)
+const textWhitespace = contains(0x09, 0x0d)
+
+/**
+ * Checks whether the code point is a *text* code point — distinct from
+ * {@link isValidCodePoint}, which gates well-formedness for decoding. A code
+ * point is text unless it is a control character: the controls are 0x0000 -
+ * 0x001F, 0x007F (DEL), and 0x0080 - 0x009F (C1), minus the whitespace block
+ * 0x0009 - 0x000D (TAB, LF, VT, FF, CR), which is legitimate in text. Every
+ * code point at or above 0x0020 that is not DEL or a C1 control is text.
+ *
+ * @type {(c: number) => boolean}
+ */
+export const isTextCodePoint = c =>
+    textWhitespace(c) || !(c0Control(c) || delAndC1Control(c))

package/fjs/text/code_point/proof.f.d.mts

@@ -0,0 +1,9 @@
+export declare const proof: {
+    eofFlush: (() => void)[];
+    isHighSurrogate: (() => void)[];
+    isLowSurrogate: (() => void)[];
+    isBmpCodePoint: (() => void)[];
+    isSupplementaryPlane: (() => void)[];
+    isValidCodePoint: (() => void)[];
+    isTextCodePoint: (() => void)[];
+};

package/fjs/text/code_point/proof.f.mjs

@@ -0,0 +1,108 @@
+import { assertEq } from '../../asserts/module.f.mjs'
+import { toArray } from '../../types/list/module.f.mjs'
+import {
+    eofFlush,
+    isBmpCodePoint,
+    isHighSurrogate,
+    isLowSurrogate,
+    isSupplementaryPlane,
+    isTextCodePoint,
+    isValidCodePoint,
+} from './module.f.mjs'
+
+/** @type {(actual: boolean, expected: boolean) => void} */
+const check = (actual, expected) => {
+    if (actual !== expected) { throw `${actual} !== ${expected}` }
+}
+
+/**
+ * A stand-in for a codec's state-to-error function.
+ *
+ * @type {(state: number) => number}
+ */
+const negate = state => -state
+
+const flush = eofFlush(negate)
+
+export const proof = {
+    eofFlush: [
+        // no leftover state: nothing is flushed, the state stays empty
+        () => {
+            const [out, next] = flush(null)
+            assertEq(toArray(out).length, 0)
+            assertEq(next, null)
+        },
+        // leftover state: exactly one error unit, then the state resets
+        () => {
+            const [out, next] = flush(42)
+            const [first, ...rest] = toArray(out)
+            assertEq(first, -42)
+            assertEq(rest.length, 0)
+            assertEq(next, null)
+        },
+    ],
+    isHighSurrogate: [
+        () => check(isHighSurrogate(0xd800), true),
+        () => check(isHighSurrogate(0xdbff), true),
+        () => check(isHighSurrogate(0xd7ff), false),
+        () => check(isHighSurrogate(0xdc00), false),
+    ],
+    isLowSurrogate: [
+        () => check(isLowSurrogate(0xdc00), true),
+        () => check(isLowSurrogate(0xdfff), true),
+        () => check(isLowSurrogate(0xdbff), false),
+        () => check(isLowSurrogate(0xe000), false),
+    ],
+    isBmpCodePoint: [
+        // lowBmp branch true
+        () => check(isBmpCodePoint(0x0000), true),
+        () => check(isBmpCodePoint(0xd7ff), true),
+        // lowBmp false, highBmp true
+        () => check(isBmpCodePoint(0xe000), true),
+        () => check(isBmpCodePoint(0xffff), true),
+        // both false: surrogate and supplementary
+        () => check(isBmpCodePoint(0xd800), false),
+        () => check(isBmpCodePoint(0x10000), false),
+    ],
+    isSupplementaryPlane: [
+        () => check(isSupplementaryPlane(0x10000), true),
+        () => check(isSupplementaryPlane(0x10ffff), true),
+        () => check(isSupplementaryPlane(0xffff), false),
+        () => check(isSupplementaryPlane(0x110000), false),
+    ],
+    isValidCodePoint: [
+        // in range, not surrogate
+        () => check(isValidCodePoint(0x0000), true),
+        () => check(isValidCodePoint(0x10ffff), true),
+        // in range, surrogate -> invalid
+        () => check(isValidCodePoint(0xd800), false),
+        () => check(isValidCodePoint(0xdfff), false),
+        // out of range -> validRange short-circuits false
+        () => check(isValidCodePoint(-1), false),
+        () => check(isValidCodePoint(0x110000), false),
+    ],
+    isTextCodePoint: [
+        // C0 controls are binary...
+        () => check(isTextCodePoint(0x00), false), // NUL
+        () => check(isTextCodePoint(0x08), false), // BS
+        () => check(isTextCodePoint(0x1b), false), // ESC
+        () => check(isTextCodePoint(0x1f), false), // US
+        // ...except the whitespace block 0x09 - 0x0D
+        () => check(isTextCodePoint(0x09), true), // TAB
+        () => check(isTextCodePoint(0x0a), true), // LF
+        () => check(isTextCodePoint(0x0b), true), // VT
+        () => check(isTextCodePoint(0x0c), true), // FF
+        () => check(isTextCodePoint(0x0d), true), // CR
+        // printable ASCII is text
+        () => check(isTextCodePoint(0x20), true), // space
+        () => check(isTextCodePoint(0x41), true), // 'A'
+        () => check(isTextCodePoint(0x7e), true), // '~'
+        // DEL and the C1 controls are binary
+        () => check(isTextCodePoint(0x7f), false), // DEL
+        () => check(isTextCodePoint(0x80), false), // C1 start
+        () => check(isTextCodePoint(0x9f), false), // C1 end
+        // above C1 is text again
+        () => check(isTextCodePoint(0xa0), true), // NBSP
+        () => check(isTextCodePoint(0x10ffff), true),
+    ],
+}

package/fjs/text/module.f.d.mts

@@ -0,0 +1,41 @@
+/**
+ * Indented text `Block` rendering and UTF-8 helpers: `flat` flattens a nested
+ * block into prefixed lines, while `utf8`/`utf8ToString` convert between
+ * strings and MSB-first UTF-8 bit vectors.
+ *
+ * @module
+ *
+ * @import { List } from '../types/list/types.ts'
+ * @import { Nullable } from '../types/nullable/types.ts'
+ * @import { Block, Item, Utf8 } from './types.ts'
+ */
+import type { List } from '../types/list/types.ts';
+import type { Nullable } from '../types/nullable/types.ts';
+import type { Block, Utf8 } from './types.ts';
+/** @type {(indent: string) => (text: Block) => List<string>} */
+export declare const flat: (indent: string) => (text: Block) => List<string>;
+/**
+ * Converts a string to an UTF-8, represented as an MSB first bit vector,
+ * returning `null` instead of throwing if the result would exceed
+ * `maxLength`.
+ *
+ * @param {string} s The input string to be converted.
+ * @returns {Nullable<Utf8>} The resulting UTF-8 bit vector, MSB first, or `null` on overflow.
+ */
+export declare const tryUtf8: (s: string) => Nullable<Utf8>;
+/**
+ * Converts a string to an UTF-8, represented as an MSB first bit vector.
+ *
+ * @param s The input string to be converted.
+ * @returns The resulting UTF-8 bit vector, MSB first.
+ *
+ * @type {(s: string) => Utf8}
+ */
+export declare const utf8: (s: string) => Utf8;
+/**
+ * Converts a UTF-8 bit vector with MSB first encoding to a string.
+ *
+ * @param {Utf8} msbV The UTF-8 bit vector with MSB first encoding.
+ * @returns {string} The resulting string.
+ */
+export declare const utf8ToString: (msbV: Utf8) => string;

package/fjs/text/module.f.mjs

@@ -0,0 +1,62 @@
+/**
+ * Indented text `Block` rendering and UTF-8 helpers: `flat` flattens a nested
+ * block into prefixed lines, while `utf8`/`utf8ToString` convert between
+ * strings and MSB-first UTF-8 bit vectors.
+ *
+ * @module
+ *
+ * @import { List } from '../types/list/types.ts'
+ * @import { Nullable } from '../types/nullable/types.ts'
+ * @import { Block, Item, Utf8 } from './types.ts'
+ */
+
+import { msb, tryU8ListToVec, u8List } from '../types/bit_vec/module.f.mjs'
+import { flatMap } from '../types/list/module.f.mjs'
+import { fromCodePointList, toCodePointList } from './utf8/module.f.mjs'
+import { stringToCodePointList, codePointListToString } from './utf16/module.f.mjs'
+import { mapUnwrap } from '../types/nullable/module.f.mjs'
+
+/** @type {(indent: string) => (text: Block) => List<string>} */
+export const flat = indent => {
+    /** @param {string} prefix */
+    const f = prefix => {
+        /** @type {(item: Item) => List<string>} */
+        const g = item =>
+            typeof (item) === 'string' ? [`${prefix}${item}`] : f(`${prefix}${indent}`)(item)
+        return flatMap(g)
+    }
+    return f('')
+}
+
+const tryU8ListToVecMsb = tryU8ListToVec(msb)
+
+/**
+ * Converts a string to an UTF-8, represented as an MSB first bit vector,
+ * returning `null` instead of throwing if the result would exceed
+ * `maxLength`.
+ *
+ * @param {string} s The input string to be converted.
+ * @returns {Nullable<Utf8>} The resulting UTF-8 bit vector, MSB first, or `null` on overflow.
+ */
+export const tryUtf8 = s =>
+    tryU8ListToVecMsb(fromCodePointList(stringToCodePointList(s)))
+
+/**
+ * Converts a string to an UTF-8, represented as an MSB first bit vector.
+ *
+ * @param s The input string to be converted.
+ * @returns The resulting UTF-8 bit vector, MSB first.
+ *
+ * @type {(s: string) => Utf8}
+ */
+export const utf8 =
+    mapUnwrap(tryUtf8)
+
+/**
+ * Converts a UTF-8 bit vector with MSB first encoding to a string.
+ *
+ * @param {Utf8} msbV The UTF-8 bit vector with MSB first encoding.
+ * @returns {string} The resulting string.
+ */
+export const utf8ToString = msbV =>
+    codePointListToString(toCodePointList(u8List(msb)(msbV)))

package/fjs/text/proof.f.d.mts

@@ -0,0 +1,13 @@
+/**
+ * @import { Block } from './types.ts'
+ */
+export declare const proof: {
+    block: () => void;
+    encoding: () => void;
+    tryUtf8RoundTrip: () => void;
+    tryUtf8Empty: () => void;
+    tryUtf8Overflow: {
+        try: () => void;
+        throw: () => void;
+    };
+};

package/fjs/text/proof.f.mjs

@@ -0,0 +1,51 @@
+/**
+ * @import { Block } from './types.ts'
+ */
+
+import { assertEq, assertNotNullish } from '../asserts/module.f.mjs'
+import { flat, utf8, utf8ToString, tryUtf8 } from './module.f.mjs'
+import { join } from '../types/string/module.f.mjs'
+import { empty, maxLengthBytes } from '../types/bit_vec/module.f.mjs'
+
+const overflowStr = 'a'.repeat(Number(maxLengthBytes) + 1)
+
+export const proof = {
+    block: () => {
+        /** @type {Block} */
+        const text = [
+            'a',
+            'b',
+            () => [
+                'c',
+                () => ['d'],
+            ],
+            'e',
+        ]
+        const result = join('\n')(flat(':')(text))
+        assertEq(result, 'a\nb\n:c\n::d\ne')
+    },
+    encoding: () => {
+        const v = utf8('Hello world!')
+        const r = utf8ToString(v)
+        assertEq(r, 'Hello world!')
+    },
+    tryUtf8RoundTrip: () => {
+        const v = assertNotNullish(tryUtf8('Hello world!'))
+        assertEq(v, utf8('Hello world!'))
+        assertEq(utf8ToString(v), 'Hello world!')
+    },
+    tryUtf8Empty: () => {
+        assertEq(tryUtf8(''), empty)
+    },
+    tryUtf8Overflow: {
+        // One byte past `maxLengthBytes`; `tryUtf8` should report `null`
+        // instead of building an oversized `bigint`, and the throwing `utf8`
+        // wrapper should raise on the same input.
+        try: () => {
+            assertEq(tryUtf8(overflowStr), null)
+        },
+        throw: () => {
+            utf8(overflowStr)
+        },
+    },
+}

package/fjs/text/sgr/module.f.d.mts

@@ -0,0 +1,61 @@
+/**
+ * ANSI Control Sequence Introducer (CSI) and Select Graphic Rendition (SGR)
+ * helpers for writing formatted terminal output and TTY-aware console streams.
+ *
+ * See `./types.ts` for the type-level API.
+ *
+ * @module
+ *
+ * @import { Write, WriteConsoles, NodeProgramOptions } from '../../effects/node/types.ts'
+ * @import { Effect } from '../../effects/types.ts'
+ * @import { Stdout, WriteText, CsiConsole } from './types.ts'
+ */
+import type { Write, WriteConsoles, NodeProgramOptions } from '../../effects/node/types.ts';
+import type { Effect } from '../../effects/types.ts';
+import type { Stdout, WriteText } from './types.ts';
+/** @type {string} */
+export declare const backspace: string;
+export type _End = 'm';
+export type _Csi = (code: number | string) => string;
+/**
+ * Control Sequence Introducer (CSI) escape sequence.
+ * https://en.wikipedia.org/wiki/ANSI_escape_code#Control_Sequence_Introducer_commands
+ *
+ * @param end - The final character that indicates the type of sequence.
+ * @returns A function that takes a code (number or string) and returns the complete ANSI escape sequence.
+ *
+ * @type {(end: _End) => _Csi}
+ */
+export declare const csi: (end: _End) => _Csi;
+/**
+ * Specialization of CSI for Select Graphic Rendition (SGR) sequences.
+ * https://en.wikipedia.org/wiki/ANSI_escape_code#SGR
+ *
+ * @type {_Csi}
+ */
+export declare const sgr: _Csi;
+/** Resets all SGR styles to terminal defaults. */
+export declare const reset: string;
+/** Enables bold/intense text rendering when supported by the terminal. */
+export declare const bold: string;
+/** Applies red foreground color to subsequent text. */
+export declare const fgRed: string;
+/** Applies green foreground color to subsequent text. */
+export declare const fgGreen: string;
+/**
+ * Creates a stateful text writer that rewrites the previous value using backspaces.
+ *
+ * @param stdout - Destination output stream.
+ * @returns A recursive writer that replaces prior text on each call.
+ *
+ * @type {(stdout: Stdout) => WriteText}
+ */
+export declare const createConsoleText: (stdout: Stdout) => WriteText;
+/**
+ * Effect-based TTY-aware write. Strips ANSI SGR sequences when the target
+ * stream is not a TTY, then encodes to UTF-8 and emits a `Write` effect.
+ * Does NOT append `\n` — callers are responsible for line termination.
+ *
+ * @type {(options: NodeProgramOptions) => (stream: WriteConsoles) => (s: string) => Effect<Write, void>}
+ */
+export declare const csiWrite: (options: NodeProgramOptions) => (stream: WriteConsoles) => (s: string) => Effect<Write, void>;