ng-form-foundry-transformers 0.3.3 → 0.3.5

package/dist/transformers/libconfig/parser.d.ts

@@ -0,0 +1,90 @@
+/**
+ * A lossless libconfig parser: source text → positioned AST.
+ *
+ * Every node carries its `[start, end)` span into the original text, and every
+ * scalar carries the emission metadata (`radix`, `L` suffix, float-ness, raw
+ * lexeme) that {@link import('./revert')} needs to write an edited value back
+ * without re-typing the setting for the consuming C program — libconfig is
+ * statically typed, so `20` and `20.0` are different types to
+ * `config_lookup_*`. Comments and formatting are not modeled: the revert
+ * splices only edited value spans, so every unedited byte survives verbatim.
+ *
+ * Implemented independently from the libconfig manual
+ * (https://hyperrealm.github.io/libconfig/libconfig_manual.html); the grammar
+ * covers: groups `{}`, arrays `[]` (homogeneous scalars), lists `()`
+ * (heterogeneous), settings `name = value;` / `name : value` with an optional
+ * `;`/`,` terminator, int (decimal/hex/binary/octal), int64 (`L`/`LL`
+ * suffix), float, bool (case-insensitive), strings with escapes and adjacent
+ * literal concatenation, `#`/`//`/`/* *​/` comments, and `@include` lines.
+ */
+/** Half-open source range of a node, in code-unit offsets. */
+export interface Span {
+    start: number;
+    end: number;
+}
+/** How an integer literal was written, so an edit re-emits the same style. */
+export interface IntMeta {
+    radix: 2 | 8 | 10 | 16;
+    /** `L`/`LL` suffix, verbatim, or empty. */
+    suffix: string;
+    /** Hex/binary/octal digit count of the literal, for width-preserving edits. */
+    digits: number;
+}
+export type CfgValue = CfgScalar | CfgGroup | CfgArray | CfgList;
+export interface CfgScalar {
+    kind: 'scalar';
+    span: Span;
+    /**
+     * `int` and `float` hold a JS number; `int64` holds the exact decimal digits
+     * as a string when the value is outside the safe integer range, a number
+     * otherwise (the string carry mirrors `core/bigint.ts`).
+     */
+    type: 'int' | 'int64' | 'float' | 'bool' | 'string';
+    value: number | string | boolean;
+    int?: IntMeta;
+}
+export interface CfgSetting {
+    name: string;
+    /** The whole setting: name through terminator (exclusive of trailing comment). */
+    span: Span;
+    value: CfgValue;
+}
+export interface CfgGroup {
+    kind: 'group';
+    span: Span;
+    /** Between the braces (the whole file for the root) — the insertion window. */
+    innerSpan: Span;
+    settings: CfgSetting[];
+}
+export interface CfgArray {
+    kind: 'array';
+    span: Span;
+    innerSpan: Span;
+    elements: CfgScalar[];
+}
+export interface CfgList {
+    kind: 'list';
+    span: Span;
+    innerSpan: Span;
+    elements: CfgValue[];
+}
+/** Options observed by the parser (a subset of the transformer's options). */
+export interface ParseOptions {
+    /**
+     * `'reject'` (default) errors on an `@include` line — the parsed form would
+     * silently show less than the C reader sees. `'opaque'` skips the directive:
+     * the line survives verbatim in the source and the included settings stay
+     * invisible to the form.
+     */
+    includes?: 'reject' | 'opaque';
+}
+/** A parse failure, pointing at the offending line and column. */
+export declare class LibconfigParseError extends Error {
+    readonly line: number;
+    readonly column: number;
+    constructor(message: string, line: number, column: number);
+}
+/** Parse a libconfig document into its root group (spans index into `source`). */
+export declare function parseLibconfig(source: string, options?: ParseOptions): CfgGroup;
+/** Scalar type family for array homogeneity: int and int64 mix, float does not. */
+export declare function family(type: CfgScalar['type']): 'integer' | 'float' | 'bool' | 'string';

package/dist/transformers/libconfig/parser.js

@@ -0,0 +1,296 @@
+"use strict";
+/**
+ * A lossless libconfig parser: source text → positioned AST.
+ *
+ * Every node carries its `[start, end)` span into the original text, and every
+ * scalar carries the emission metadata (`radix`, `L` suffix, float-ness, raw
+ * lexeme) that {@link import('./revert')} needs to write an edited value back
+ * without re-typing the setting for the consuming C program — libconfig is
+ * statically typed, so `20` and `20.0` are different types to
+ * `config_lookup_*`. Comments and formatting are not modeled: the revert
+ * splices only edited value spans, so every unedited byte survives verbatim.
+ *
+ * Implemented independently from the libconfig manual
+ * (https://hyperrealm.github.io/libconfig/libconfig_manual.html); the grammar
+ * covers: groups `{}`, arrays `[]` (homogeneous scalars), lists `()`
+ * (heterogeneous), settings `name = value;` / `name : value` with an optional
+ * `;`/`,` terminator, int (decimal/hex/binary/octal), int64 (`L`/`LL`
+ * suffix), float, bool (case-insensitive), strings with escapes and adjacent
+ * literal concatenation, `#`/`//`/`/* *​/` comments, and `@include` lines.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LibconfigParseError = void 0;
+exports.parseLibconfig = parseLibconfig;
+exports.family = family;
+/** A parse failure, pointing at the offending line and column. */
+class LibconfigParseError extends Error {
+    constructor(message, line, column) {
+        super(`libconfig parse error at ${line}:${column} — ${message}`);
+        this.line = line;
+        this.column = column;
+        this.name = 'LibconfigParseError';
+    }
+}
+exports.LibconfigParseError = LibconfigParseError;
+const NAME_RE = /^[A-Za-z*][-A-Za-z0-9_*.]*/;
+const INT_RE = /^[-+]?(0[xX][0-9A-Fa-f]+|0[bB][01]+|0[oO][0-7]+|[0-9]+)(LL?)?/;
+const FLOAT_RE = /^[-+]?(([0-9]*\.[0-9]+|[0-9]+\.[0-9]*)([eE][-+]?[0-9]+)?|[0-9]+[eE][-+]?[0-9]+)/;
+const BOOL_RE = /^(true|false)(?![-A-Za-z0-9_*.])/i;
+/** Parse a libconfig document into its root group (spans index into `source`). */
+function parseLibconfig(source, options) {
+    return new Parser(source, options?.includes ?? 'reject').parseRoot();
+}
+class Parser {
+    constructor(src, includes) {
+        this.src = src;
+        this.includes = includes;
+        this.pos = 0;
+    }
+    parseRoot() {
+        const settings = this.parseSettings(undefined);
+        return {
+            kind: 'group',
+            span: { start: 0, end: this.src.length },
+            innerSpan: { start: 0, end: this.src.length },
+            settings,
+        };
+    }
+    /** Settings until `closer` (or EOF for the root). */
+    parseSettings(closer) {
+        const settings = [];
+        for (;;) {
+            this.skipTrivia();
+            if (this.pos >= this.src.length) {
+                if (closer)
+                    this.fail(`expected '${closer}'`);
+                return settings;
+            }
+            if (closer && this.src[this.pos] === closer)
+                return settings;
+            if (this.src[this.pos] === '@') {
+                this.handleInclude();
+                continue;
+            }
+            settings.push(this.parseSetting(settings));
+        }
+    }
+    parseSetting(siblings) {
+        const start = this.pos;
+        const name = this.match(NAME_RE) ?? this.fail('expected a setting name');
+        if (siblings.some((s) => s.name === name)) {
+            this.fail(`duplicate setting name '${name}' in the same group`);
+        }
+        this.skipTrivia();
+        if (this.src[this.pos] !== '=' && this.src[this.pos] !== ':') {
+            this.fail(`expected '=' or ':' after '${name}'`);
+        }
+        this.pos++;
+        this.skipTrivia();
+        const value = this.parseValue();
+        this.skipTrivia();
+        // Terminator is optional in the grammar: `;`, `,`, or nothing.
+        if (this.src[this.pos] === ';' || this.src[this.pos] === ',')
+            this.pos++;
+        return { name, span: { start, end: this.pos }, value };
+    }
+    parseValue() {
+        const c = this.src[this.pos];
+        if (c === '{')
+            return this.parseGroup();
+        if (c === '[')
+            return this.parseCollection('[', ']', 'array');
+        if (c === '(')
+            return this.parseCollection('(', ')', 'list');
+        return this.parseScalar();
+    }
+    parseGroup() {
+        const start = this.pos++;
+        const innerStart = this.pos;
+        const settings = this.parseSettings('}');
+        const innerEnd = this.pos;
+        this.pos++; // consume '}'
+        return {
+            kind: 'group',
+            span: { start, end: this.pos },
+            innerSpan: { start: innerStart, end: innerEnd },
+            settings,
+        };
+    }
+    parseCollection(open, close, kind) {
+        const start = this.pos++;
+        const innerStart = this.pos;
+        const elements = [];
+        for (;;) {
+            this.skipTrivia();
+            if (this.pos >= this.src.length)
+                this.fail(`expected '${close}'`);
+            if (this.src[this.pos] === close)
+                break;
+            const element = kind === 'array' ? this.parseScalar() : this.parseValue();
+            elements.push(element);
+            this.skipTrivia();
+            if (this.src[this.pos] === ',')
+                this.pos++;
+            else if (this.src[this.pos] !== close)
+                this.fail(`expected ',' or '${close}'`);
+        }
+        const innerEnd = this.pos;
+        this.pos++; // consume closer
+        if (kind === 'array') {
+            const nonScalar = elements.find((e) => e.kind !== 'scalar');
+            if (nonScalar)
+                this.fail('arrays hold scalars only (use a list for groups)');
+            const types = new Set(elements.map((e) => family(e.type)));
+            if (types.size > 1)
+                this.fail('array elements must share one scalar type');
+            return {
+                kind: 'array',
+                span: { start, end: this.pos },
+                innerSpan: { start: innerStart, end: innerEnd },
+                elements: elements,
+            };
+        }
+        return {
+            kind: 'list',
+            span: { start, end: this.pos },
+            innerSpan: { start: innerStart, end: innerEnd },
+            elements,
+        };
+    }
+    parseScalar() {
+        const start = this.pos;
+        const rest = this.src.slice(this.pos);
+        const bool = BOOL_RE.exec(rest);
+        if (bool) {
+            this.pos += bool[0].length;
+            return { kind: 'scalar', span: { start, end: this.pos }, type: 'bool', value: bool[0].toLowerCase() === 'true' };
+        }
+        if (rest[0] === '"')
+            return this.parseString();
+        // Float before int: `1.5` must not lex as int `1` + junk.
+        const float = FLOAT_RE.exec(rest);
+        if (float) {
+            this.pos += float[0].length;
+            return { kind: 'scalar', span: { start, end: this.pos }, type: 'float', value: Number(float[0]) };
+        }
+        const int = INT_RE.exec(rest);
+        if (int) {
+            this.pos += int[0].length;
+            return this.intScalar(int[0], { start, end: this.pos });
+        }
+        return this.fail('expected a value');
+    }
+    intScalar(lexeme, span) {
+        const sign = lexeme[0] === '-' ? '-' : '';
+        const unsigned = lexeme.replace(/^[-+]/, '');
+        const suffix = /LL?$/i.exec(unsigned)?.[0] ?? '';
+        const body = suffix ? unsigned.slice(0, -suffix.length) : unsigned;
+        const prefix = body.slice(0, 2).toLowerCase();
+        const radix = prefix === '0x' ? 16 : prefix === '0b' ? 2 : prefix === '0o' ? 8 : 10;
+        const digits = radix === 10 ? body : body.slice(2);
+        const big = BigInt(sign + (radix === 10 ? digits : body.slice(0, 2) + digits));
+        const meta = { radix, suffix, digits: digits.length };
+        // Values past 2^53 ride as exact decimal strings (the core bigint strategy);
+        // the suffix and radix stay in the metadata for the write-back.
+        const safe = big >= BigInt(Number.MIN_SAFE_INTEGER) && big <= BigInt(Number.MAX_SAFE_INTEGER);
+        const type = suffix || !safe ? 'int64' : 'int';
+        return {
+            kind: 'scalar',
+            span,
+            type,
+            value: safe ? Number(big) : big.toString(),
+            int: meta,
+        };
+    }
+    parseString() {
+        const start = this.pos;
+        let value = '';
+        // Adjacent literals concatenate: `"a" "b"` (possibly across lines) is "ab".
+        for (;;) {
+            value += this.parseStringLiteral();
+            const resume = this.pos;
+            this.skipTrivia();
+            if (this.src[this.pos] !== '"') {
+                this.pos = resume; // trivia after the last literal belongs to the caller
+                break;
+            }
+        }
+        return { kind: 'scalar', span: { start, end: this.pos }, type: 'string', value };
+    }
+    parseStringLiteral() {
+        this.pos++; // opening quote
+        let out = '';
+        while (this.pos < this.src.length) {
+            const c = this.src[this.pos];
+            if (c === '"') {
+                this.pos++;
+                return out;
+            }
+            if (c === '\\') {
+                const esc = this.src[this.pos + 1];
+                if (esc === 'x') {
+                    out += String.fromCharCode(parseInt(this.src.slice(this.pos + 2, this.pos + 4), 16));
+                    this.pos += 4;
+                    continue;
+                }
+                const simple = { n: '\n', r: '\r', t: '\t', f: '\f', v: '\v', '\\': '\\', '"': '"' };
+                out += (esc !== undefined && simple[esc]) || esc || '';
+                this.pos += 2;
+                continue;
+            }
+            if (c === '\n')
+                this.fail('unterminated string');
+            out += c;
+            this.pos++;
+        }
+        return this.fail('unterminated string');
+    }
+    handleInclude() {
+        const lineEnd = this.src.indexOf('\n', this.pos);
+        if (this.includes === 'reject') {
+            this.fail("'@include' is not supported: the form would show less than the C reader sees. " +
+                "Pass includes: 'opaque' to keep the directive verbatim and edit only this file's own settings");
+        }
+        this.pos = lineEnd === -1 ? this.src.length : lineEnd + 1;
+    }
+    /** Skip whitespace and all three comment forms. */
+    skipTrivia() {
+        for (;;) {
+            const c = this.src[this.pos];
+            if (c === ' ' || c === '\t' || c === '\r' || c === '\n') {
+                this.pos++;
+                continue;
+            }
+            if (c === '#' || (c === '/' && this.src[this.pos + 1] === '/')) {
+                const nl = this.src.indexOf('\n', this.pos);
+                this.pos = nl === -1 ? this.src.length : nl;
+                continue;
+            }
+            if (c === '/' && this.src[this.pos + 1] === '*') {
+                const end = this.src.indexOf('*/', this.pos + 2);
+                if (end === -1)
+                    this.fail('unterminated block comment');
+                this.pos = end + 2;
+                continue;
+            }
+            return;
+        }
+    }
+    match(re) {
+        const m = re.exec(this.src.slice(this.pos));
+        if (!m)
+            return undefined;
+        this.pos += m[0].length;
+        return m[0];
+    }
+    fail(message) {
+        const upto = this.src.slice(0, this.pos);
+        const line = upto.split('\n').length;
+        const column = this.pos - upto.lastIndexOf('\n');
+        throw new LibconfigParseError(message, line, column);
+    }
+}
+/** Scalar type family for array homogeneity: int and int64 mix, float does not. */
+function family(type) {
+    return type === 'int' || type === 'int64' ? 'integer' : type;
+}

package/dist/transformers/libconfig/revert.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Write an edited form value back onto libconfig source by span splicing.
+ *
+ * Counterpart of the AST/extraction in {@link import('./parser')} and
+ * {@link import('./schema')}. Instead of regenerating text from the AST, the
+ * edited value is compared against the AST node by node and only the spans
+ * that actually changed are replaced in the original text — every unedited
+ * byte (comments, indentation, `=` vs `:`, terminators, delimiter style)
+ * survives verbatim.
+ *
+ * Emission is type-preserving, because the consuming C program reads settings
+ * through typed lookups: a float stays a float (`21` edits to `21.0`), a hex
+ * literal re-emits in hex at its original digit width, an int64 keeps its
+ * `L`/`LL` suffix, and values beyond 2^53 travel as exact decimal strings.
+ */
+import type { CfgGroup } from './parser';
+/** Apply `value` onto the parsed `root` of `source`, returning the new text. */
+export declare function applyValueToSource(source: string, root: CfgGroup, value: Record<string, unknown>): string;

package/dist/transformers/libconfig/revert.js

@@ -0,0 +1,243 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyValueToSource = applyValueToSource;
+const schema_1 = require("./schema");
+/** Apply `value` onto the parsed `root` of `source`, returning the new text. */
+function applyValueToSource(source, root, value) {
+    const edits = [];
+    patchGroup(source, root, value, edits);
+    edits.sort((a, b) => b.start - a.start);
+    let out = source;
+    for (const e of edits)
+        out = out.slice(0, e.start) + e.text + out.slice(e.end);
+    return out;
+}
+function patchGroup(src, group, value, edits) {
+    for (const setting of group.settings) {
+        if (!value || !(setting.name in value)) {
+            edits.push(deleteSetting(src, setting));
+            continue;
+        }
+        patchValue(src, setting.value, value[setting.name], edits);
+    }
+    const known = new Set(group.settings.map((s) => s.name));
+    const added = Object.keys(value ?? {}).filter((k) => !known.has(k));
+    if (added.length) {
+        edits.push(insertionEdit(src, group, added.map((k) => `${k} = ${serialize(value[k], '')};`)));
+    }
+}
+function patchValue(src, node, value, edits) {
+    switch (node.kind) {
+        case 'scalar': {
+            if (node.value === value)
+                return;
+            edits.push({ ...node.span, text: emitScalar(value, node) });
+            return;
+        }
+        case 'group': {
+            if (isRecord(value))
+                return patchGroup(src, node, value, edits);
+            edits.push({ ...node.span, text: serialize(value, '') }); // shape change: regenerate
+            return;
+        }
+        case 'array': {
+            if (Array.isArray(value))
+                return patchElements(src, node.elements, node, value, edits);
+            // The read-only raw carry of an untyped empty array: leave verbatim.
+            if (typeof value === 'string' && value === (0, schema_1.raw)(node, src))
+                return;
+            edits.push({ ...node.span, text: serialize(value, '') });
+            return;
+        }
+        case 'list': {
+            const shape = (0, schema_1.listShape)(node);
+            if (shape === 'groups' && Array.isArray(value)) {
+                return patchElements(src, node.elements, node, value, edits);
+            }
+            if (shape === 'scalars' && Array.isArray(value)) {
+                return patchElements(src, node.elements, node, value, edits);
+            }
+            if (shape === 'empty' && Array.isArray(value)) {
+                // Editable only under a JSON Schema; entries splice inside the delimiters.
+                if (value.length) {
+                    edits.push({ start: node.innerSpan.start, end: node.innerSpan.start, text: value.map((v) => serialize(v, '')).join(', ') });
+                }
+                return;
+            }
+            // Heterogeneous (read-only raw carry) or unchanged empty: only replace on
+            // a genuine mismatch with a non-raw value shape — otherwise leave verbatim.
+            if (typeof value === 'string' && value === (0, schema_1.raw)(node, src))
+                return;
+            if (value !== undefined && typeof value !== 'string') {
+                edits.push({ ...node.span, text: serialize(value, '') });
+            }
+            return;
+        }
+    }
+}
+/** Element-wise patch of an array/list: edit in place, then grow or shrink. */
+function patchElements(src, elements, collection, value, edits) {
+    const shared = Math.min(elements.length, value.length);
+    for (let i = 0; i < shared; i++)
+        patchValue(src, elements[i], value[i], edits);
+    if (value.length > elements.length) {
+        const items = value.slice(elements.length).map((v) => serialize(v, ''));
+        const at = elements.length ? elements[elements.length - 1].span.end : collection.innerSpan.start;
+        edits.push({ start: at, end: at, text: (elements.length ? ', ' : '') + items.join(', ') });
+    }
+    else if (value.length < elements.length) {
+        const start = value.length ? elements[value.length - 1].span.end : collection.innerSpan.start;
+        edits.push({ start, end: elements[elements.length - 1].span.end, text: '' });
+    }
+}
+/**
+ * Deletion takes the whole setting line when nothing else lives on it: the
+ * leading indent, the setting, trailing spaces, a trailing `#`/`//` comment,
+ * and the newline. A setting sharing its line only gives up its own span.
+ */
+function deleteSetting(src, setting) {
+    let start = setting.span.start;
+    while (start > 0 && (src[start - 1] === ' ' || src[start - 1] === '\t'))
+        start--;
+    const atLineStart = start === 0 || src[start - 1] === '\n';
+    let end = setting.span.end;
+    while (end < src.length && (src[end] === ' ' || src[end] === '\t'))
+        end++;
+    if (src[end] === '#' || (src[end] === '/' && src[end + 1] === '/')) {
+        const nl = src.indexOf('\n', end);
+        end = nl === -1 ? src.length : nl;
+    }
+    if (atLineStart && src[end] === '\n')
+        return { start, end: end + 1, text: '' };
+    return { start: setting.span.start, end, text: '' };
+}
+/** Indent of the group's first setting, for inserted lines (2 spaces fallback). */
+function settingIndent(src, group) {
+    const first = group.settings[0];
+    if (!first)
+        return '  ';
+    const lineStart = src.lastIndexOf('\n', first.span.start - 1) + 1;
+    const lead = src.slice(lineStart, first.span.start);
+    return /^[ \t]*$/.test(lead) ? lead : '  ';
+}
+/**
+ * Where new settings go: on fresh lines after the last setting's own line (so
+ * a trailing inline comment keeps its setting), else at the start of an empty
+ * braced group, else appended at the end of an empty root document.
+ */
+function insertionEdit(src, group, settings) {
+    const isRoot = group.span.start === 0 && group.span.end === src.length;
+    const limit = isRoot ? src.length : group.innerSpan.end;
+    const last = group.settings[group.settings.length - 1];
+    if (last) {
+        const indent = settingIndent(src, group);
+        const nl = src.indexOf('\n', last.span.end);
+        if (nl !== -1 && nl <= limit) {
+            return { start: nl, end: nl, text: settings.map((s) => `\n${indent}${s}`).join('') };
+        }
+        return { start: limit, end: limit, text: settings.map((s) => ` ${s}`).join('') };
+    }
+    const at = isRoot ? limit : group.innerSpan.start;
+    const text = settings.map((s) => `${isRoot ? '' : ' '}${s}`).join(' ');
+    return { start: at, end: at, text: isRoot ? text + '\n' : text + ' ' };
+}
+/** Format an edited scalar in the style its AST node was written in. */
+function emitScalar(value, node) {
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    if (typeof value === 'string') {
+        // The int64 string carry: exact digits back, with the original suffix.
+        if (node.type === 'int64' && typeof node.value === 'string') {
+            if (!/^[-+]?[0-9]+$/.test(value)) {
+                throw new Error(`'${value}' is not an integer: this setting carries a 64-bit integer as a string`);
+            }
+            return value + (node.int?.suffix ?? '');
+        }
+        return quote(value);
+    }
+    if (typeof value === 'number') {
+        if (node.type === 'float')
+            return floatLiteral(value);
+        if ((node.type === 'int' || node.type === 'int64') && Number.isInteger(value)) {
+            return intLiteral(value, node.int);
+        }
+        return floatLiteral(value); // a fractional edit into an int slot: emit honestly
+    }
+    return serialize(value, '');
+}
+/** Integer in the source's radix and width, suffix preserved. */
+function intLiteral(value, meta) {
+    if (!meta || meta.radix === 10)
+        return String(value) + (meta?.suffix ?? '');
+    const prefix = meta.radix === 16 ? '0x' : meta.radix === 2 ? '0b' : '0o';
+    const digits = Math.abs(value).toString(meta.radix).toUpperCase().padStart(meta.digits, '0');
+    return (value < 0 ? '-' : '') + prefix + digits + meta.suffix;
+}
+/** A float literal that stays a float: integral values gain `.0`. */
+function floatLiteral(value) {
+    const s = String(value);
+    return Number.isInteger(value) && !/[.eE]/.test(s) ? `${s}.0` : s;
+}
+function quote(value) {
+    let out = '"';
+    for (const ch of value) {
+        const code = ch.codePointAt(0);
+        if (ch === '"')
+            out += '\\"';
+        else if (ch === '\\')
+            out += '\\\\';
+        else if (ch === '\n')
+            out += '\\n';
+        else if (ch === '\r')
+            out += '\\r';
+        else if (ch === '\t')
+            out += '\\t';
+        else if (ch === '\f')
+            out += '\\f';
+        else if (code < 0x20)
+            out += '\\x' + code.toString(16).padStart(2, '0');
+        else
+            out += ch;
+    }
+    return out + '"';
+}
+/**
+ * Serialize a brand-new value with no AST counterpart (an added setting, a
+ * grown collection). Typing is value-driven here: integral numbers emit as
+ * ints, fractional as floats — a host that needs a float-typed `21.0` for a
+ * fresh setting should send `21.0`-producing edits through an existing float
+ * slot or accept the int typing (documented beta limitation).
+ */
+function serialize(value, indent) {
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    if (typeof value === 'number')
+        return String(value);
+    if (typeof value === 'string')
+        return /^[-+]?[0-9]+$/.test(value) && isBigIntString(value) ? value + 'L' : quote(value);
+    if (Array.isArray(value)) {
+        const inner = value.map((v) => serialize(v, indent)).join(', ');
+        const grouped = value.some((v) => isRecord(v) || Array.isArray(v));
+        return grouped ? `( ${inner} )` : `[ ${inner} ]`;
+    }
+    if (isRecord(value)) {
+        const body = Object.keys(value)
+            .map((k) => `${k} = ${serialize(value[k], indent)};`)
+            .join(' ');
+        return `{ ${body} }`;
+    }
+    return 'true'; // null/undefined have no libconfig literal; unreachable via typed forms
+}
+/** An integer string that exceeds the double-safe range (the bigint carry). */
+function isBigIntString(value) {
+    try {
+        const big = BigInt(value);
+        return big > BigInt(Number.MAX_SAFE_INTEGER) || big < BigInt(Number.MIN_SAFE_INTEGER);
+    }
+    catch {
+        return false;
+    }
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}