@limaformat/lima 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to `@limaformat/lima` are documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+This package's version number tracks its own release history and is
+independent of the Lima specification version — [Lima Core
+1.0](https://github.com/limaformat/lima/blob/main/docs/lima-core-1.0-spec.md)
+and [Lima References
+1.0](https://github.com/limaformat/lima/blob/main/docs/lima-references-1.0-spec.md)
+are both frozen regardless of what this file shows.
+
+## [0.1.0] — Unreleased
+
+Initial release.
+
+### Added
+
+- `parseCore(input, options?)` — Lima Core 1.0 only, no reference
+  resolution.
+- `parse(input, options?)` / `parseReferences(input, options?)` — Core plus
+  the References 1.0 extension (`($key)` document references, `(%key)`
+  external partials).
+- Zero runtime dependencies.
+- Verified against the shared, implementation-independent conformance
+  corpus (250 cases as of this release; count pinned by a test — see
+  [`docs/guide.md`](https://github.com/limaformat/lima/blob/main/docs/guide.md)
+  and
+  [`docs/corpus-design/`](https://github.com/limaformat/lima/tree/main/docs/corpus-design)).

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Michael Kortstiege
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# @limaformat/lima
+
+**LIMA Is Metadata Annotation** — a small, predictable frontmatter format.
+A deliberate, focused subset of YAML: the part frontmatter actually needs,
+with well-defined types, no surprises, and zero runtime dependencies.
+
+```bash
+npm install @limaformat/lima
+# or
+bun add @limaformat/lima
+```
+
+```ts
+import { parse } from '@limaformat/lima'
+
+const result = parse(`
+title: Hello World
+published: 2024-03-01
+draft: false
+tags:
+  - javascript
+  - webdev
+`)
+
+// {
+//   title: 'Hello World',
+//   published: 2024-03-01T00:00:00.000Z,  // a Date
+//   draft: false,
+//   tags: ['javascript', 'webdev']
+// }
+```
+
+`parse` accepts the raw content **between** the frontmatter delimiters
+(`---`) — stripping them is the caller's job.
+
+Two functions are exported:
+
+- `parseCore(input, options?)` — the base format only.
+- `parse(input, options?)` (alias for `parseReferences`) — adds
+  `($key)` document references and `(%key)` external partials.
+
+```ts
+parse(frontmatter, { strict: true })
+parse(frontmatter, { partials: { author: 'Alice' } })
+```
+
+Full syntax reference, the References extension, resource limits, strict
+mode, and the complete API:
+**[docs/guide.md](https://github.com/limaformat/lima/blob/main/docs/guide.md)**.
+
+Why Lima exists, the case against YAML, and security rationale:
+**[repository README](https://github.com/limaformat/lima#readme)**.
+
+The [Lima Core 1.0](https://github.com/limaformat/lima/blob/main/docs/lima-core-1.0-spec.md)
+and [Lima References 1.0](https://github.com/limaformat/lima/blob/main/docs/lima-references-1.0-spec.md)
+specifications are the normative source of truth — this package implements
+them exactly, verified against a
+[250-case conformance corpus](https://github.com/limaformat/lima/tree/main/corpus)
+(count pinned by a test) shared with any other Lima implementation.
+
+Migrating existing YAML frontmatter:
+[docs/migrating-from-yaml.md](https://github.com/limaformat/lima/blob/main/docs/migrating-from-yaml.md).
+Static site generator integration status:
+[docs/integrations.md](https://github.com/limaformat/lima/blob/main/docs/integrations.md).
+
+## License
+
+ISC — see
+[LICENSE](https://github.com/limaformat/lima/blob/main/js/LICENSE) (also
+included in this package as `LICENSE`).

package/dist/block-cursor.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Allocation-free physical-line cursor over one top-level block extent.
+ * Positions are UTF-16 code-unit offsets. Structural boundaries are ASCII;
+ * indentation additionally follows the complete whitespace predicate used by
+ * `trimStart()`, matching the existing block grammar.
+ */
+export declare class BlockCursor {
+    readonly source: string;
+    readonly rangeStart: number;
+    readonly rangeEnd: number;
+    lineStart: number;
+    lineEnd: number;
+    contentStart: number;
+    indent: number;
+    asciiIndent: number;
+    lineIndex: number;
+    valid: boolean;
+    maxIndent: number;
+    private nextStart;
+    constructor(source: string, rangeStart: number, rangeEnd: number);
+    next(): boolean;
+    get empty(): boolean;
+    get firstCode(): number;
+}

package/dist/block-cursor.js

@@ -0,0 +1,71 @@
+import { isTrimWhitespace } from './chars.js';
+/**
+ * Allocation-free physical-line cursor over one top-level block extent.
+ * Positions are UTF-16 code-unit offsets. Structural boundaries are ASCII;
+ * indentation additionally follows the complete whitespace predicate used by
+ * `trimStart()`, matching the existing block grammar.
+ */
+export class BlockCursor {
+    source;
+    rangeStart;
+    rangeEnd;
+    lineStart = 0;
+    lineEnd = 0;
+    contentStart = 0;
+    indent = 0;
+    asciiIndent = 0;
+    lineIndex = -1;
+    valid = false;
+    maxIndent = 0;
+    nextStart;
+    constructor(source, rangeStart, rangeEnd) {
+        this.source = source;
+        this.rangeStart = rangeStart;
+        this.rangeEnd = rangeEnd;
+        this.nextStart = rangeStart;
+    }
+    next() {
+        if (this.nextStart >= this.rangeEnd) {
+            this.valid = false;
+            return false;
+        }
+        const start = this.nextStart;
+        const newline = this.source.indexOf('\n', start);
+        const end = newline === -1 || newline >= this.rangeEnd ? this.rangeEnd : newline;
+        let content = start;
+        while (content < end && this.source.charCodeAt(content) === 0x20)
+            content++;
+        const asciiEnd = content;
+        // After ordinary space indentation, printable ASCII starts content
+        // immediately. Only ASCII control whitespace or non-ASCII code units
+        // need the complete trimStart-compatible predicate.
+        if (content < end) {
+            let code = this.source.charCodeAt(content);
+            if ((code >= 0x09 && code <= 0x0d) || code > 0x7f) {
+                do {
+                    if (!isTrimWhitespace(code))
+                        break;
+                    content++;
+                    code = this.source.charCodeAt(content);
+                } while (content < end);
+            }
+        }
+        this.lineStart = start;
+        this.lineEnd = end;
+        this.contentStart = content;
+        this.asciiIndent = asciiEnd - start;
+        this.indent = content - start;
+        if (this.indent > this.maxIndent)
+            this.maxIndent = this.indent;
+        this.lineIndex++;
+        this.valid = true;
+        this.nextStart = newline === -1 || newline >= this.rangeEnd ? this.rangeEnd : newline + 1;
+        return true;
+    }
+    get empty() {
+        return this.contentStart === this.lineEnd;
+    }
+    get firstCode() {
+        return this.source.charCodeAt(this.contentStart);
+    }
+}

package/dist/block.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Core §7 block collections (sequences and mappings) — a direct structural
+ * port of the legacy block parser, generic over its output representation
+ * (see `builder.ts`) so `parseCore` can build the public native result
+ * directly, without also building the References-only annotated
+ * `PositionedValue` tree it never needs. No reference-resolution concerns
+ * at all (no `resolve()` call anywhere, no array-as-sequence-item
+ * reference-shape check — that error class cannot occur here since Core
+ * never resolves a reference in the first place).
+ */
+import { type ParseContext } from './normalize.js';
+import type { ValueBuilder } from './builder.js';
+export declare const findKeySep: (s: string) => number;
+/** Complete block grammar over one UTF-16 source range. */
+export type BlockDepthRisk = {
+    mayExceed: boolean;
+};
+export declare const parseBlockRange: <V, M>(source: string, start: number, end: number, ctx: ParseContext, baseLine: number, builder: ValueBuilder<V, M>, depthRisk: BlockDepthRisk) => V | null;

package/dist/block.js

@@ -0,0 +1,305 @@
+/**
+ * Core §7 block collections (sequences and mappings) — a direct structural
+ * port of the legacy block parser, generic over its output representation
+ * (see `builder.ts`) so `parseCore` can build the public native result
+ * directly, without also building the References-only annotated
+ * `PositionedValue` tree it never needs. No reference-resolution concerns
+ * at all (no `resolve()` call anywhere, no array-as-sequence-item
+ * reference-shape check — that error class cannot occur here since Core
+ * never resolves a reference in the first place).
+ */
+import { LString } from './value.js';
+import { checkKeyLength, checkDuplicateKey, checkScalarLimit, NESTING_DEPTH_LIMIT } from './normalize.js';
+import { stripKeyQuotes, unescapeDQ, stripComment, parseQuotedOrTyped, } from './scalars.js';
+import { parseFlowMapping, parseFlowOrScalarValue } from './flow.js';
+import { LimaError } from './errors.js';
+import { isTrimWhitespace } from './chars.js';
+import { BlockCursor } from './block-cursor.js';
+const DASH_PREFIX_RE = /^-\s+/;
+export const findKeySep = (s) => {
+    const first = s.charCodeAt(0);
+    if (first === 39 || first === 34) {
+        let i = 1;
+        while (i < s.length && s.charCodeAt(i) !== first)
+            i++;
+        if (s.charCodeAt(i + 1) === 58 && s.charCodeAt(i + 2) === 32)
+            return i + 1;
+        return -1;
+    }
+    return s.indexOf(': ');
+};
+/**
+ * Recursively parses a block value from a mutable physical-line cursor over
+ * the original source. Strings are materialized only when grammar or scalar
+ * parsing needs their content.
+ */
+/** `source.slice(start, end).trim()` with no temporary untrimmed substring. */
+const trimSlice = (source, start, end) => {
+    if (start < end) {
+        const first = source.charCodeAt(start);
+        const last = source.charCodeAt(end - 1);
+        // Printable ASCII cannot be consumed by trim(), except U+0020 SPACE.
+        // Canonical frontmatter keys/values overwhelmingly have printable,
+        // non-space ASCII boundaries, so avoid both Unicode predicate calls.
+        if (first > 0x20 && first < 0x7f && last > 0x20 && last < 0x7f) {
+            return source.slice(start, end);
+        }
+    }
+    while (start < end && isTrimWhitespace(source.charCodeAt(start)))
+        start++;
+    while (end > start && isTrimWhitespace(source.charCodeAt(end - 1)))
+        end--;
+    return source.slice(start, end);
+};
+const cursorContent = (cursor) => cursor.source.slice(cursor.contentStart, cursor.lineEnd);
+const cursorAfterDash = (cursor) => {
+    const start = cursor.contentStart;
+    const end = cursor.lineEnd;
+    if (start + 1 === end)
+        return '';
+    let content = start + 1;
+    if (!isTrimWhitespace(cursor.source.charCodeAt(content)))
+        return cursor.source.slice(start, end);
+    while (content < end && isTrimWhitespace(cursor.source.charCodeAt(content)))
+        content++;
+    return cursor.source.slice(content, end);
+};
+/** Shared block grammar consuming one mutable physical-line cursor. */
+const parseCursorBlock = (cursor, baseIndent, ctx, baseLine, builder) => {
+    let items = null;
+    let entries = null;
+    let pendingItem = null;
+    const startLine = cursor.lineIndex;
+    while (cursor.valid) {
+        const line = baseLine + cursor.lineIndex;
+        if (cursor.empty || cursor.firstCode === 35) {
+            cursor.next();
+            continue;
+        }
+        const indent = cursor.indent;
+        if (indent < baseIndent)
+            break;
+        if (indent > baseIndent) {
+            const trimmed = cursorContent(cursor);
+            if (items !== null && pendingItem !== null) {
+                const colonPos = findKeySep(trimmed);
+                if (colonPos !== -1) {
+                    const key = stripKeyQuotes(trimSlice(trimmed, 0, colonPos));
+                    checkKeyLength(key, () => line);
+                    let raw = trimSlice(trimmed, colonPos + 2, trimmed.length);
+                    if (raw.includes('#'))
+                        raw = stripComment(raw);
+                    builder.setMapping(pendingItem, key, parseFlowOrScalarValue(raw, ctx, line, builder));
+                    cursor.next();
+                }
+                else if (trimmed.endsWith(':')) {
+                    const key = stripKeyQuotes(trimSlice(trimmed, 0, trimmed.length - 1));
+                    checkKeyLength(key, () => line);
+                    cursor.next();
+                    while (cursor.valid && cursor.empty)
+                        cursor.next();
+                    if (cursor.valid && cursor.indent > indent) {
+                        const nested = parseCursorBlock(cursor, cursor.indent, ctx, baseLine, builder);
+                        builder.setMapping(pendingItem, key, nested ?? builder.null(line));
+                    }
+                    else
+                        builder.setMapping(pendingItem, key, builder.null(line));
+                }
+                else {
+                    if (ctx.strict)
+                        throw new LimaError({ code: 'INVALID_INDENTATION', line,
+                            message: `LIMA: unexpected syntax in array item continuation at line ${line}: "${trimmed}"` });
+                    cursor.next();
+                }
+            }
+            else {
+                if (ctx.strict)
+                    throw new LimaError({ code: 'INVALID_INDENTATION', line,
+                        message: `LIMA: unexpected indentation at line ${line}: "${trimmed}"` });
+                cursor.next();
+            }
+            continue;
+        }
+        if (cursor.firstCode === 45) {
+            if (pendingItem !== null) {
+                items.push(builder.mapping(pendingItem, line));
+                pendingItem = null;
+            }
+            if (items === null)
+                items = [];
+            if (entries !== null) {
+                if (ctx.strict)
+                    throw new LimaError({ code: 'INVALID_INDENTATION', line,
+                        message: `LIMA: mixed array and map entries for the same key at line ${line}` });
+                cursor.next();
+                continue;
+            }
+            let afterDash = cursorAfterDash(cursor);
+            if (afterDash.includes('#'))
+                afterDash = stripComment(afterDash);
+            const first = afterDash.charCodeAt(0);
+            if (first !== 34 && first !== 39 && first !== 45 && first !== 123 &&
+                afterDash.indexOf(': ') === -1 && !afterDash.endsWith(':')) {
+                items.push(parseQuotedOrTyped(afterDash, ctx, line, false, builder));
+                cursor.next();
+                continue;
+            }
+            const flowMap = parseFlowMapping(afterDash, ctx, line, builder);
+            const colonPos = findKeySep(afterDash);
+            if (flowMap !== null) {
+                items.push(flowMap);
+                cursor.next();
+            }
+            else if (afterDash === '-' || DASH_PREFIX_RE.test(afterDash)) {
+                if (ctx.strict)
+                    throw new LimaError({ code: 'INVALID_INDENTATION', line,
+                        message: `LIMA: nested block sequence at line ${line}: "${cursorContent(cursor)}"` });
+                items.push(builder.null(line));
+                cursor.next();
+                while (cursor.valid) {
+                    if (cursor.empty || cursor.source.charCodeAt(cursor.contentStart) === 35) {
+                        cursor.next();
+                        continue;
+                    }
+                    if (cursor.indent <= baseIndent)
+                        break;
+                    cursor.next();
+                }
+            }
+            else if (colonPos !== -1) {
+                const keyFirst = afterDash.charCodeAt(0);
+                const keyLast = afterDash.charCodeAt(colonPos - 1);
+                const keyRaw = keyFirst > 0x20 && keyFirst < 0x7f && keyLast > 0x20 && keyLast < 0x7f
+                    ? afterDash.slice(0, colonPos) : trimSlice(afterDash, 0, colonPos);
+                const key = keyFirst === 34 || keyFirst === 39 ? stripKeyQuotes(keyRaw) : keyRaw;
+                checkKeyLength(key, () => line);
+                const valueStart = colonPos + 2;
+                const valueFirst = afterDash.charCodeAt(valueStart);
+                const valueLast = afterDash.charCodeAt(afterDash.length - 1);
+                const raw = valueFirst > 0x20 && valueFirst < 0x7f && valueLast > 0x20 && valueLast < 0x7f
+                    ? afterDash.slice(valueStart) : trimSlice(afterDash, valueStart, afterDash.length);
+                pendingItem = builder.createMappingWith(key, parseFlowOrScalarValue(raw, ctx, line, builder));
+                cursor.next();
+                while (cursor.valid && cursor.indent > baseIndent) {
+                    const continuationLine = baseLine + cursor.lineIndex;
+                    const start = cursor.contentStart, end = cursor.lineEnd;
+                    const cfirst = cursor.source.charCodeAt(start);
+                    if (cfirst === 34 || cfirst === 39 || cfirst === 35)
+                        break;
+                    const sep = cursor.source.indexOf(': ', start);
+                    if (sep === -1 || sep >= end)
+                        break;
+                    const keyLast = cursor.source.charCodeAt(sep - 1);
+                    const ckey = cfirst > 0x20 && cfirst < 0x7f && keyLast > 0x20 && keyLast < 0x7f
+                        ? cursor.source.slice(start, sep) : trimSlice(cursor.source, start, sep);
+                    if (!ckey)
+                        break;
+                    checkKeyLength(ckey, () => continuationLine);
+                    const valueStart = sep + 2;
+                    const valueFirst = cursor.source.charCodeAt(valueStart);
+                    const valueLast = cursor.source.charCodeAt(end - 1);
+                    let value = valueFirst > 0x20 && valueFirst < 0x7f && valueLast > 0x20 && valueLast < 0x7f
+                        ? cursor.source.slice(valueStart, end) : trimSlice(cursor.source, valueStart, end);
+                    if (value.includes('#'))
+                        value = stripComment(value);
+                    builder.setMapping(pendingItem, ckey, parseFlowOrScalarValue(value, ctx, continuationLine, builder));
+                    cursor.next();
+                }
+            }
+            else if (afterDash.endsWith(':')) {
+                const key = stripKeyQuotes(trimSlice(afterDash, 0, afterDash.length - 1));
+                checkKeyLength(key, () => line);
+                cursor.next();
+                while (cursor.valid && cursor.empty)
+                    cursor.next();
+                if (cursor.valid && cursor.indent > baseIndent) {
+                    const nested = parseCursorBlock(cursor, cursor.indent, ctx, baseLine, builder);
+                    pendingItem = builder.createMappingWith(key, nested ?? builder.null(line));
+                }
+                else
+                    pendingItem = builder.createMappingWith(key, builder.null(line));
+            }
+            else {
+                const q = afterDash.charCodeAt(0);
+                if ((q === 34 || q === 39) && afterDash.charCodeAt(afterDash.length - 1) === q) {
+                    const inner = afterDash.slice(1, -1);
+                    const value = q === 34 ? unescapeDQ(inner, ctx.strict, line) : inner.replace(/\\'/g, "'");
+                    checkScalarLimit(LString(value), line);
+                    items.push(builder.string(value, line, true));
+                }
+                else
+                    items.push(parseQuotedOrTyped(afterDash, ctx, line, false, builder));
+                cursor.next();
+            }
+        }
+        else {
+            const trimmed = cursorContent(cursor);
+            if (items !== null) {
+                if (ctx.strict)
+                    throw new LimaError({ code: 'INVALID_INDENTATION', line,
+                        message: `LIMA: mixed map and array entries for the same key at line ${line}` });
+                cursor.next();
+                continue;
+            }
+            const colonPos = findKeySep(trimmed);
+            if (colonPos !== -1) {
+                if (entries === null)
+                    entries = builder.createMapping();
+                const key = stripKeyQuotes(trimSlice(trimmed, 0, colonPos));
+                checkKeyLength(key, () => line);
+                if (ctx.strict || ctx.onWarning !== undefined)
+                    checkDuplicateKey(builder.hasMappingKey(entries, key), key, line, ctx);
+                let raw = trimSlice(trimmed, colonPos + 2, trimmed.length);
+                if (raw.includes('#'))
+                    raw = stripComment(raw);
+                builder.setMapping(entries, key, parseFlowOrScalarValue(raw, ctx, line, builder));
+                cursor.next();
+            }
+            else if (trimmed.endsWith(':')) {
+                if (entries === null)
+                    entries = builder.createMapping();
+                const key = stripKeyQuotes(trimSlice(trimmed, 0, trimmed.length - 1));
+                checkKeyLength(key, () => line);
+                if (ctx.strict || ctx.onWarning !== undefined)
+                    checkDuplicateKey(builder.hasMappingKey(entries, key), key, line, ctx);
+                cursor.next();
+                while (cursor.valid && cursor.empty)
+                    cursor.next();
+                if (cursor.valid && cursor.indent > baseIndent) {
+                    const nested = parseCursorBlock(cursor, cursor.indent, ctx, baseLine, builder);
+                    builder.setMapping(entries, key, nested ?? builder.null(line));
+                }
+                else
+                    builder.setMapping(entries, key, builder.null(line));
+            }
+            else {
+                if (ctx.strict)
+                    throw new LimaError({ code: 'INVALID_INDENTATION', line,
+                        message: `LIMA: indented freetext without a block scalar marker at line ${line}: "${trimmed}"` });
+                cursor.next();
+            }
+        }
+    }
+    if (pendingItem !== null)
+        items.push(builder.mapping(pendingItem, baseLine + startLine));
+    return items !== null ? builder.array(items, baseLine + startLine) :
+        entries !== null ? builder.mapping(entries, baseLine + startLine) : null;
+};
+export const parseBlockRange = (source, start, end, ctx, baseLine, builder, depthRisk) => {
+    const cursor = new BlockCursor(source, start, end);
+    if (!cursor.next())
+        return null;
+    while (cursor.valid && cursor.empty)
+        cursor.next();
+    if (!cursor.valid)
+        return null;
+    const baseIndent = cursor.asciiIndent;
+    const value = parseCursorBlock(cursor, baseIndent, ctx, baseLine, builder);
+    // Recursive block containers require strictly increasing integer
+    // indentation. At one indentation level a sequence-item mapping can add
+    // one container and Core flow syntax at most two more, so delta + 4 is a
+    // conservative depth bound below the document root.
+    if (cursor.maxIndent - baseIndent + 4 > NESTING_DEPTH_LIMIT)
+        depthRisk.mayExceed = true;
+    return value;
+};

package/dist/builder.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Parameterizes the Core grammar (`scalars.ts`, `flow.ts`, `block.ts`) over
+ * its output representation, so the same parsing control flow can produce
+ * either the References-needed annotated `PositionedValue` tree or, for
+ * `parseCore`, the public native result directly — without a second,
+ * hand-copied parser that could drift from the first (see core.ts's
+ * `nativeBuilder` and scalars.ts's `positionedBuilder`).
+ *
+ * `M` is the builder's own in-progress mapping accumulator type — a bare
+ * `Map<string, V>` for `positionedBuilder` (later wrapped into a
+ * `PositionedValue` mapping node by `mapping()`), a prototype-free
+ * `Record<string, V>` for `nativeBuilder` (where the accumulator already
+ * *is* the finished public shape, so `mapping()` is a no-op pass-through —
+ * this is what lets `parseCore` skip building and copying an intermediate
+ * `Map` for every mapping, including the top-level document root).
+ *
+ * Claude Code review note: an earlier version of this interface typed the
+ * accumulator as `unknown`, requiring every concrete builder to `as`-cast
+ * it back to its real type at every one of `createMapping`/`hasMappingKey`/
+ * `setMapping`/`mappingMaxDepth`/`mapping` — full call-site type-checking on
+ * `block.ts`/`flow.ts`/`scalars.ts` (they only ever go through these
+ * methods, never touch `M` directly) with none of the safety lost in
+ * exchange, purely by making `M` a second generic parameter instead. This
+ * is compile-time-only: generics are erased, so the emitted JS — and
+ * therefore performance — is identical either way, verified by benchmark.
+ */
+export interface ValueBuilder<V, M = Map<string, V>> {
+    null(line: number): V;
+    bool(value: boolean, line: number): V;
+    int(value: number, line: number): V;
+    float(value: number, line: number): V;
+    string(value: string, line: number, quoted: boolean): V;
+    instant(value: Date, line: number): V;
+    array(items: V[], line: number): V;
+    createMapping(): M;
+    createMappingWith(key: string, value: V): M;
+    hasMappingKey(entries: M, key: string): boolean;
+    setMapping(entries: M, key: string, value: V): void;
+    mappingMaxDepth(entries: M, depthOf: (value: V) => number): number;
+    mapping(entries: M, line: number): V;
+}

package/dist/builder.js

@@ -0,0 +1 @@
+export {};

package/dist/chars.d.ts

@@ -0,0 +1,2 @@
+/** Exact ECMAScript WhiteSpace + LineTerminator set for one UTF-16 code unit. */
+export declare const isTrimWhitespace: (c: number) => boolean;

package/dist/chars.js

@@ -0,0 +1,4 @@
+/** Exact ECMAScript WhiteSpace + LineTerminator set for one UTF-16 code unit. */
+export const isTrimWhitespace = (c) => c === 0x0009 || (c >= 0x000a && c <= 0x000d) || c === 0x0020 || c === 0x00a0 ||
+    c === 0x1680 || (c >= 0x2000 && c <= 0x200a) || c === 0x2028 || c === 0x2029 ||
+    c === 0x202f || c === 0x205f || c === 0x3000 || c === 0xfeff;

package/dist/core.d.ts

@@ -0,0 +1,73 @@
+/**
+ * LIMA Core 1.0 parser — reference-unaware by construction (Appendix B:
+ * reference resolution is exclusively the concern of the optional
+ * References extension). `($key)`/`(%key)`-shaped text is never
+ * recognised or coerced here; it simply falls through as an ordinary
+ * string, indistinguishable from any other unrecognised text.
+ *
+ * `parseCoreWithPositions` builds the internal annotated value tree — a
+ * `PositionedValue` per node, carrying the source line and (for strings)
+ * whether it came from quoted syntax. This one-pass output is the shared
+ * primitive the References layer (`references.ts`) builds on: it locates
+ * reference-shaped string leaves, and reads each site's line directly off
+ * its node instead of re-deriving position information after the fact.
+ * `parseCore` is the public, position-free projection of the same parse.
+ *
+ * The grammar itself lives in `normalize.ts` (shared context/limits),
+ * `scalars.ts` (dates, numbers, quoting, the `PositionedValue` tree type),
+ * `flow.ts` (`[...]`/`{...}`), and `block.ts` (indentation-based sequences
+ * and mappings) — this file is the orchestrator that ties them together.
+ */
+import { type LimaValue } from './value.js';
+import { type ParseContext, type Diagnostic } from './normalize.js';
+import { type PositionedValue } from './scalars.js';
+import type { ValueBuilder } from './builder.js';
+export type { Diagnostic, ParseContext } from './normalize.js';
+export { NESTING_DEPTH_LIMIT, SCALAR_LENGTH_LIMIT } from './normalize.js';
+export type { PositionedValue, InsertedAt } from './scalars.js';
+export { toPlainValue } from './scalars.js';
+type Meta = Record<string, unknown>;
+export type CoreOptions = {
+    strict?: boolean;
+    /** Core §11.2: callback for non-strict warnings (e.g. duplicate keys). Discarded if omitted. */
+    onWarning?: (diagnostic: Diagnostic) => void;
+};
+/**
+ * Parses LIMA Core 1.0 syntax into the internal annotated value tree —
+ * every node carrying its source line, string leaves additionally carrying
+ * whether they came from quoted syntax. `($key)`/`(%key)` text is left
+ * exactly as written; nothing here ever inspects or resolves it. The
+ * primitive the References layer (`references.ts`) builds on.
+ */
+export declare const parseCoreWithPositions: (frontMatter: string, ctx: ParseContext) => Map<string, PositionedValue>;
+/** The public result shape (Core §11.1): every value `toNative*` can produce. */
+export type NativeValue = null | boolean | number | string | Date | NativeValue[] | {
+    [key: string]: NativeValue;
+};
+/**
+ * The `ValueBuilder<NativeValue>` — `parseCore`'s fast path. Every scalar
+ * builder is the identity function: unlike `positionedBuilder`, there is no
+ * wrapper object to allocate at all, only the value itself. `array` and
+ * `mapping` build the exact public shape directly (a real array; a
+ * prototype-free object per Core §11.1), so `parseCore` never needs a
+ * separate conversion pass over an intermediate tree afterward.
+ */
+export declare const nativeBuilder: ValueBuilder<NativeValue, Record<string, NativeValue>>;
+/** Converts a Lima value to a plain, native JS value (the public result shape). */
+export declare const toNative: (v: LimaValue) => NativeValue;
+/**
+ * `toNative(toPlainValue(v))` in one pass instead of two full tree walks —
+ * matters most for large, reference-expanded results (many copies of a
+ * sizeable partial), where the position/quoted-stripping pass and the
+ * native-conversion pass would otherwise each independently visit every
+ * node of the same, potentially large, final tree.
+ */
+export declare const toNativeFromPositioned: (v: PositionedValue) => NativeValue;
+/**
+ * Public Core 1.0 entry point. Never resolves `($key)`/`(%key)` text — see
+ * the module doc comment. Equivalent in observable behavior to calling
+ * `parseReferences()` with no partials on a document that happens to
+ * contain no references, except that here reference-shaped text is
+ * guaranteed to always pass through unresolved, even in strict mode.
+ */
+export declare const parseCore: <T extends Record<string, unknown> = Meta>(frontMatter: string, options?: CoreOptions) => T;