@voithos-labs/aragonite 0.10.1

package/dist/core/inline/visibility.js

@@ -0,0 +1,144 @@
+/**
+ * What a marker-hiding mode leaves on screen. `inline-render.ts` decides which bytes become which
+ * span; this decides which of those spans the reader sees, and it is the one home for that rule:
+ * the DOM walk (`cursor/widget-offset.ts`) is its other consumer, in the space that has a caret.
+ * The two answers are held together by `test/invariants/screen-truth.property.test.ts`, not by
+ * convention. Context vocabulary: `docs/design/live-mode.md` § 2.
+ */
+import { renderInlineNodes } from '../inline-render';
+import { widgetSourceRange } from './inline-widgets';
+import {} from '../../presentation-mode';
+const FAMILY_CLASS = {
+    marker: 'md-marker',
+    'fence-line': 'md-fence-line',
+    'ref-label': 'md-ref-label'
+};
+/** Every family at once, for a caller reading spans back out of a rendered fragment. */
+export const MARKER_FAMILY_SELECTOR = Object.values(FAMILY_CLASS)
+    .map((cls) => `.${cls}`)
+    .join(', ');
+/**
+ * The family `el` belongs to, or null for anything else. A `contenteditable="false"` marker is
+ * the ambient prefix island, which keeps its box in every mode (`ambient/ambient-cursor.ts`), so
+ * it belongs to no family.
+ */
+export function markerFamilyOf(el) {
+    const classes = el.classList;
+    if (classes.contains(FAMILY_CLASS.marker)) {
+        return el.getAttribute('contenteditable') === 'false' ? null : 'marker';
+    }
+    if (classes.contains(FAMILY_CLASS['fence-line']))
+        return 'fence-line';
+    if (classes.contains(FAMILY_CLASS['ref-label']))
+        return 'ref-label';
+    return null;
+}
+/** Whether the content-empty override paints `family` (`styles/editor.css`, same scoping). A
+ *  reference label is resolution metadata rather than chrome a caret types against, so it stays
+ *  hidden, and a container holding only labels has no paint to promise. */
+export function familyPaintsAlone(family) {
+    return family !== 'ref-label';
+}
+/**
+ * What the reader sees on a container painting under `mode`. `chromePaints` is that container's
+ * own stamp condition (live-mode.md § 4.1), which reading declines: it takes no keystrokes, so a
+ * construct with nothing behind its chrome may paint nothing there. The preview rungs' per-span
+ * reveal is DOM state and stays with the walk; this answers for an unrevealed container.
+ */
+export function screenVisibility(mode, container) {
+    switch (mode) {
+        case 'source':
+            return { hidesMarkers: false, chromePaints: false };
+        case 'reading':
+            return { hidesMarkers: true, chromePaints: false };
+        case 'live':
+        case 'preview-block':
+        case 'preview-inline':
+            return { hidesMarkers: true, chromePaints: container.chromePaints };
+        default: {
+            const unhandled = mode;
+            return unhandled;
+        }
+    }
+}
+/**
+ * The content behind every marker family, whatever the container paints: the reading a rewrite's
+ * before/after conservation diff needs, since chrome folds the moment content arrives and a diff
+ * against the screen would read that fold as bytes lost. Sound only past a
+ * {@link paintsOnlyChrome} gate — over chrome the reader IS looking at, this reading calls those
+ * bytes unseen and licenses dropping them.
+ */
+export const CONTENT_VISIBILITY = { hidesMarkers: true, chromePaints: false };
+/** A container whose chrome stands over no content: every family the override paints does. */
+const CHROME_STANDS_ALONE = { hidesMarkers: true, chromePaints: true };
+/** Whether a `family` span paints NOTHING under `ctx` — the one hiding rule, before any preview
+ *  reveal. */
+export function familyHidesText(family, ctx) {
+    return ctx.hidesMarkers && !(ctx.chromePaints && familyPaintsAlone(family));
+}
+/**
+ * `nodes` as runs of raw bytes, each carrying what it paints under `ctx`. Read off the rendered
+ * DOM rather than derived per kind, because which bytes a construct shows only the painter
+ * answers (G4.33): a caller re-deriving that drifts from what paints, which is the only thing the
+ * answer is worth anything as. Top-level nodes render one at a time, so a CLIPPED list (a join
+ * seam's surviving side) keeps honest offsets instead of a running count that assumes contiguity.
+ */
+export function visibleRuns(nodes, raw, ctx, opts = {}) {
+    const runs = [];
+    for (const node of nodes) {
+        collectRuns(renderInlineNodes([node], raw, opts), node.start, ctx, runs);
+    }
+    return runs;
+}
+/** The text a reader SEES for `nodes` — every run `ctx` leaves on screen, in source order. */
+export function renderedText(nodes, raw, ctx, opts = {}) {
+    let out = '';
+    for (const run of visibleRuns(nodes, raw, ctx, opts))
+        if (run.visible)
+            out += run.text;
+    return out;
+}
+/**
+ * Whether `nodes` are chrome standing over nothing, and therefore ALL on screen (live-mode.md
+ * § 4.1). The inline half of the content-empty stamp, for a seam with no DOM to read the stamp
+ * off: a license over bytes the reader never saw has nothing to claim here. A block's OWN chrome
+ * (a `## ` prefix, a fence line) sits outside the inline content range, so an empty one answers
+ * false and the surfaces that own it are unaffected.
+ */
+export function paintsOnlyChrome(nodes, raw, opts = {}) {
+    return (renderedText(nodes, raw, CONTENT_VISIBILITY, opts) === '' &&
+        renderedText(nodes, raw, CHROME_STANDS_ALONE, opts) !== '');
+}
+function collectRuns(fragment, start, ctx, out) {
+    let at = start;
+    const stack = [];
+    // Reversed push, so pop order is source order — which `at` advances along.
+    const pushChildren = (parent, hidden) => {
+        const children = parent.childNodes;
+        for (let i = children.length - 1; i >= 0; i--)
+            stack.push({ dom: children[i], hidden });
+    };
+    pushChildren(fragment, false);
+    while (stack.length > 0) {
+        const { dom, hidden } = stack.pop();
+        if (dom.nodeType === Node.TEXT_NODE) {
+            const text = dom.textContent ?? '';
+            out.push({ start: at, end: at + text.length, text, visible: !hidden });
+            at += text.length;
+            continue;
+        }
+        if (dom.nodeType !== Node.ELEMENT_NODE)
+            continue;
+        const el = dom;
+        // Only an atomic widget's shell carries a source range here, and it is the one element
+        // whose text is not its bytes — so the range is both the test and the re-sync.
+        const source = widgetSourceRange(el);
+        if (source !== null) {
+            out.push({ ...source, text: el.textContent ?? '', visible: !hidden });
+            at = source.end;
+            continue;
+        }
+        const family = markerFamilyOf(el);
+        pushChildren(el, hidden || (family !== null && familyHidesText(family, ctx)));
+    }
+}

package/dist/core/inline/walk.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The one iterative pre-order over an inline tree. Nesting depth is input-controlled (a `**` run
+ * nests one construct per pair), so a per-level call frame overflows the stack and strands the
+ * block in the unhealable failed-block fallback. Dependency-free, so the scan reaches it without
+ * closing a cycle through the inline entry point.
+ */
+import type { InlineNode } from '../nodes';
+/**
+ * Each node, then its children, in source order. `descend` declines a node's children — the node
+ * itself is still yielded, and is asked only when it has any. Yields nodes only: what a reader
+ * SEES stays the render path's question (G4.33). Each child list is snapshotted onto the stack
+ * when its parent pops, so a consumer that rewrites `children` must finish the walk first.
+ */
+export declare function inlineDescendants(nodes: readonly InlineNode[], descend?: (node: InlineNode) => boolean): Generator<InlineNode>;

package/dist/core/inline/walk.js

@@ -0,0 +1,29 @@
+/**
+ * The one iterative pre-order over an inline tree. Nesting depth is input-controlled (a `**` run
+ * nests one construct per pair), so a per-level call frame overflows the stack and strands the
+ * block in the unhealable failed-block fallback. Dependency-free, so the scan reaches it without
+ * closing a cycle through the inline entry point.
+ */
+/**
+ * Each node, then its children, in source order. `descend` declines a node's children — the node
+ * itself is still yielded, and is asked only when it has any. Yields nodes only: what a reader
+ * SEES stays the render path's question (G4.33). Each child list is snapshotted onto the stack
+ * when its parent pops, so a consumer that rewrites `children` must finish the walk first.
+ */
+export function* inlineDescendants(nodes, descend) {
+    // Reversed push, so pop order is source order.
+    const stack = [];
+    for (let i = nodes.length - 1; i >= 0; i--)
+        stack.push(nodes[i]);
+    while (stack.length > 0) {
+        const node = stack.pop();
+        yield node;
+        const children = node.children;
+        if (!children || children.length === 0)
+            continue;
+        if (descend && !descend(node))
+            continue;
+        for (let i = children.length - 1; i >= 0; i--)
+            stack.push(children[i]);
+    }
+}

package/dist/core/inline-render.d.ts

@@ -0,0 +1,48 @@
+/**
+ * DOM renderer for InlineNode trees. Over a widget-free range the fragment's textContent equals
+ * raw.slice. Atomic widgets break that by design, contributing their own text or none and
+ * carrying source bytes on `data-source-*`, so a raw offset is recovered only through the shared
+ * walk (cursor/widget-offset.ts), never by counting textContent. Stated both ways by G2.4.
+ *
+ * Which of the spans minted here a mode leaves on screen is `inline/visibility.ts`.
+ */
+import type { InlineNode } from './nodes';
+export type ImageLoadPolicy = 'auto' | 'placeholder';
+export interface RenderInlineOptions {
+    renderImagesAsWidgets?: boolean;
+    resolveImageUrl?: (rawUrl: string) => string;
+    /** Render-time href rewrite for links/autolinks (default identity). */
+    resolveLinkUrl?: (rawUrl: string) => string;
+    /** Whether remote images auto-load (default) or defer to a placeholder. */
+    imageLoadPolicy?: ImageLoadPolicy;
+    /** Injected by the component layer so `core/` owns no image specifics; absent renders alt-only. */
+    buildImageWidget?: (node: InlineNode, raw: string, opts: {
+        resolveImageUrl: (rawUrl: string) => string;
+        imageLoadPolicy: ImageLoadPolicy;
+    }) => Node;
+    /**
+     * Mounts a `component`-kind widget in the atomic-island wrapper. Injected for the same reason
+     * as `buildImageWidget`; absent or null falls the widget back to its raw source.
+     */
+    buildPortalWidget?: (node: InlineNode, raw: string) => HTMLElement | null;
+    /**
+     * Stamp marker spans with the construct's raw range, so preview-inline's reveal trigger can
+     * address them. Attributes only, leaving textContent and the offset walk untouched. Off by
+     * default so the DOM stays byte-identical outside preview-inline.
+     */
+    tagConstructMarkers?: boolean;
+}
+/** The one href funnel for every sink — a consumer's rewrite, then the scheme allowlist; undefined
+ *  reads as "render inert". Exported: the link card's Open button hands over a user-typed URL. */
+export declare function resolveHref(opts: RenderInlineOptions, url: string | undefined): string | undefined;
+export declare function renderInlineNodes(nodes: InlineNode[], raw: string, opts?: RenderInlineOptions): DocumentFragment;
+export interface OffsetResult {
+    node: InlineNode;
+    localOffset: number;
+}
+/**
+ * The leaf containing `offset`, preferring the right node at a boundary; `offset === end` only
+ * matches the last node. Model-layer, touching no DOM: the DOM counterpart is
+ * `findDomTextOffsetTarget` in cursor/widget-offset.ts.
+ */
+export declare function findNodeAtOffset(nodes: InlineNode[], offset: number): OffsetResult | null;

package/dist/core/inline-render.js

@@ -0,0 +1,322 @@
+/**
+ * DOM renderer for InlineNode trees. Over a widget-free range the fragment's textContent equals
+ * raw.slice. Atomic widgets break that by design, contributing their own text or none and
+ * carrying source bytes on `data-source-*`, so a raw offset is recovered only through the shared
+ * walk (cursor/widget-offset.ts), never by counting textContent. Stated both ways by G2.4.
+ *
+ * Which of the spans minted here a mode leaves on screen is `inline/visibility.ts`.
+ */
+import { buildCoreInlineWidget } from './inline/inline-widgets';
+import { isAllowedHrefScheme } from './url-policy';
+// ── Marker helpers ──────────────────────────────────────────────────────────
+function markerSpan(text) {
+    const span = document.createElement('span');
+    span.className = 'md-marker';
+    span.textContent = text;
+    return span;
+}
+function tagConstruct(el, node, opts) {
+    if (opts.tagConstructMarkers) {
+        el.setAttribute('data-construct-start', String(node.start));
+        el.setAttribute('data-construct-end', String(node.end));
+    }
+    return el;
+}
+// The verbatim-source fallback for kinds that render no widget, so every character round-trips.
+function sourceSpan(raw, node, className) {
+    const span = document.createElement('span');
+    span.className = className;
+    span.textContent = raw.slice(node.start, node.end);
+    return span;
+}
+/** The one href funnel for every sink — a consumer's rewrite, then the scheme allowlist; undefined
+ *  reads as "render inert". Exported: the link card's Open button hands over a user-typed URL. */
+export function resolveHref(opts, url) {
+    if (url === undefined)
+        return undefined;
+    const resolved = (opts.resolveLinkUrl ?? ((u) => u))(url);
+    // A type-violating resolver returning null/undefined degrades to an inert span, never a throw.
+    if (typeof resolved !== 'string')
+        return undefined;
+    return isAllowedHrefScheme(resolved) ? resolved : undefined;
+}
+// ── Inline code ─────────────────────────────────────────────────────────────
+function renderInlineCode(node, raw, opts) {
+    const frag = document.createDocumentFragment();
+    // Every span is a slice of raw, never a parsed field that happens to agree — and each is its
+    // OWN slice: the opening fence is capped at half the node and the closing one read back off
+    // the tail, so a node nobody parsed (a plugin mint over unfenced bytes) still emits its bytes
+    // exactly once (G2.4).
+    const fenceLimit = node.start + Math.floor((node.end - node.start) / 2);
+    let contentStart = node.start;
+    while (contentStart < fenceLimit && raw[contentStart] === '`')
+        contentStart++;
+    const contentEnd = node.end - (contentStart - node.start);
+    frag.appendChild(tagConstruct(markerSpan(raw.slice(node.start, contentStart)), node, opts));
+    const code = document.createElement('code');
+    code.className = 'inline-code-content';
+    code.textContent = raw.slice(contentStart, contentEnd);
+    frag.appendChild(code);
+    frag.appendChild(tagConstruct(markerSpan(raw.slice(contentEnd, node.end)), node, opts));
+    return frag;
+}
+// ── Wrapped spans (emphasis / strong / strikethrough) ───────────────────────
+function openWrapped(node, raw, tag, opts, container) {
+    const children = node.children ?? [];
+    let openEnd;
+    let closeStart;
+    if (children.length > 0) {
+        openEnd = children[0].start;
+        closeStart = children[children.length - 1].end;
+    }
+    else {
+        // No children, so the entire interior is markers; split it in half.
+        const mid = node.start + Math.floor((node.end - node.start) / 2);
+        openEnd = mid;
+        closeStart = mid;
+    }
+    container.appendChild(tagConstruct(markerSpan(raw.slice(node.start, openEnd)), node, opts));
+    const wrapper = document.createElement(tag);
+    const closeMarker = tagConstruct(markerSpan(raw.slice(closeStart, node.end)), node, opts);
+    return {
+        nodes: children,
+        index: 0,
+        content: document.createDocumentFragment(),
+        close(content) {
+            wrapper.appendChild(content);
+            container.appendChild(wrapper);
+            container.appendChild(closeMarker);
+        }
+    };
+}
+// ── Links ────────────────────────────────────────────────────────────────────
+// Markers come from raw.slice: the parsed url/title can differ from the source bytes. Every
+// split point is clamped to node.end — a plugin mint need not carry the bytes GFM's own link
+// does, and a search running past the node would render the NEXT node's source (G2.4).
+function openLink(node, raw, opts, container) {
+    const children = node.children ?? [];
+    if (children.length === 0) {
+        // Empty link text: [](url)
+        const bracket = raw.indexOf(']', node.start);
+        const mid = bracket !== -1 && bracket < node.end ? bracket : node.end;
+        container.appendChild(tagConstruct(markerSpan(raw.slice(node.start, mid)), node, opts));
+        if (mid < node.end) {
+            container.appendChild(tagConstruct(markerSpan(raw.slice(mid, node.end)), node, opts));
+        }
+        return null;
+    }
+    const lastChild = children[children.length - 1];
+    // The close marker splits into the text bracket's `]` and the trailing marker. Reference forms
+    // get their own `md-ref-label` class so CSS can dim them harder than inline markers.
+    const closingTextBracket = lastChild.end < node.end && raw[lastChild.end] === ']'
+        ? raw.slice(lastChild.end, lastChild.end + 1)
+        : '';
+    const trailingMarker = raw.slice(lastChild.end + (closingTextBracket ? 1 : 0), node.end);
+    container.appendChild(tagConstruct(markerSpan(raw.slice(node.start, children[0].start)), node, opts));
+    const href = resolveHref(opts, node.url);
+    const linkEl = document.createElement(href !== undefined ? 'a' : 'span');
+    linkEl.className = href !== undefined ? 'md-link-content' : 'md-link-content md-link-blocked';
+    if (href !== undefined) {
+        linkEl.setAttribute('href', href);
+        // The author's title, else the resolved destination: live mode hides the URL, and hover
+        // is the one affordance disclosing where an untitled link actually goes.
+        linkEl.setAttribute('title', node.title ?? href);
+    }
+    const trailing = [];
+    if (closingTextBracket) {
+        trailing.push(tagConstruct(markerSpan(closingTextBracket), node, opts));
+    }
+    if (trailingMarker) {
+        if (node.label !== undefined) {
+            const span = document.createElement('span');
+            span.className = 'md-ref-label';
+            span.textContent = trailingMarker;
+            trailing.push(tagConstruct(span, node, opts));
+        }
+        else {
+            trailing.push(tagConstruct(markerSpan(trailingMarker), node, opts));
+        }
+    }
+    return {
+        nodes: children,
+        index: 0,
+        content: document.createDocumentFragment(),
+        close(content) {
+            linkEl.appendChild(content);
+            container.appendChild(linkEl);
+            for (const marker of trailing)
+                container.appendChild(marker);
+        }
+    };
+}
+// ── Autolinks ────────────────────────────────────────────────────────────────
+/**
+ * The angle form's `<`/`>` are construct syntax, so they render as markers the mode CSS can hide;
+ * the bare URL/www/email forms are url text throughout. Read off the raw bytes, never `node.url`:
+ * the bare forms synthesize a url (`http://`, `mailto:`) that is not a slice of the source.
+ */
+function appendAutolink(node, raw, opts, container) {
+    const href = resolveHref(opts, node.url);
+    const el = document.createElement(href !== undefined ? 'a' : 'span');
+    el.className = href !== undefined ? 'md-autolink' : 'md-autolink md-link-blocked';
+    if (href !== undefined)
+        el.setAttribute('href', href);
+    const isAngleForm = raw[node.start] === '<' && raw[node.end - 1] === '>';
+    const textStart = isAngleForm ? node.start + 1 : node.start;
+    const textEnd = isAngleForm ? node.end - 1 : node.end;
+    el.textContent = raw.slice(textStart, textEnd);
+    if (isAngleForm)
+        container.appendChild(markerSpan(raw.slice(node.start, textStart)));
+    container.appendChild(el);
+    if (isAngleForm)
+        container.appendChild(markerSpan(raw.slice(textEnd, node.end)));
+}
+// ── Images ───────────────────────────────────────────────────────────────────
+/**
+ * The widget-free image path (a kind that declines image widgets, or no injected builder).
+ * The alt text stays undimmed, so a reading-mode marker collapse leaves it behind.
+ */
+function appendImageSource(node, raw, opts, container) {
+    const altText = node.alt ?? '';
+    const altStart = node.start + 2;
+    const altEnd = altStart + altText.length;
+    // `alt` locates the split and never supplies text (openLink's rule), and only where it is
+    // literally those bytes: a minted image's markers need not be a GFM image's. Unlocatable
+    // falls back to unmarked source, since a construct nobody can decompose would collapse whole.
+    if (altEnd > node.end || !raw.startsWith(altText, altStart)) {
+        container.appendChild(document.createTextNode(raw.slice(node.start, node.end)));
+        return;
+    }
+    container.appendChild(tagConstruct(markerSpan(raw.slice(node.start, altStart)), node, opts));
+    container.appendChild(document.createTextNode(raw.slice(altStart, altEnd)));
+    container.appendChild(tagConstruct(markerSpan(raw.slice(altEnd, node.end)), node, opts));
+}
+// ── Main renderer ────────────────────────────────────────────────────────────
+/** Returns a frame for the node's children; the driver owns the descent, off the call stack. */
+function renderNode(node, raw, opts, container) {
+    switch (node.kind) {
+        case 'text':
+            container.appendChild(document.createTextNode(raw.slice(node.start, node.end)));
+            return null;
+        case 'inlineCode':
+            container.appendChild(renderInlineCode(node, raw, opts));
+            return null;
+        case 'emphasis':
+            return openWrapped(node, raw, 'em', opts, container);
+        case 'strong':
+            return openWrapped(node, raw, 'strong', opts, container);
+        case 'strikethrough':
+            return openWrapped(node, raw, 's', opts, container);
+        case 'hardLineBreak': {
+            // A text node carries the line ending so textContent equals raw byte-for-byte;
+            // a `<br>` would diverge across browsers.
+            const breakRaw = raw.slice(node.start, node.end);
+            const nlIdx = breakRaw.indexOf('\n');
+            // A node carrying no line ending (a plugin mint) is all marker: a -1 here would
+            // slice from the end and drop bytes.
+            const lineEndingStart = nlIdx === -1
+                ? breakRaw.length
+                : nlIdx > 0 && breakRaw[nlIdx - 1] === '\r'
+                    ? nlIdx - 1
+                    : nlIdx;
+            if (lineEndingStart > 0) {
+                container.appendChild(markerSpan(breakRaw.slice(0, lineEndingStart)));
+            }
+            container.appendChild(document.createTextNode(breakRaw.slice(lineEndingStart)));
+            return null;
+        }
+        case 'link':
+            return openLink(node, raw, opts, container);
+        case 'image': {
+            const renderWidgets = opts.renderImagesAsWidgets ?? true;
+            if (renderWidgets && opts.buildImageWidget) {
+                container.appendChild(opts.buildImageWidget(node, raw, {
+                    resolveImageUrl: opts.resolveImageUrl ?? ((u) => u),
+                    imageLoadPolicy: opts.imageLoadPolicy ?? 'auto'
+                }));
+            }
+            else {
+                appendImageSource(node, raw, opts, container);
+            }
+            return null;
+        }
+        case 'autolink':
+            appendAutolink(node, raw, opts, container);
+            return null;
+        case 'escape':
+            container.appendChild(markerSpan(raw[node.start]));
+            container.appendChild(document.createTextNode(raw.slice(node.start + 1, node.end)));
+            return null;
+        case 'unresolvedReference':
+            container.appendChild(sourceSpan(raw, node, node.refKind === 'image'
+                ? 'md-unresolved-ref md-unresolved-ref-image'
+                : 'md-unresolved-ref'));
+            return null;
+        case 'entityReference':
+        case 'rawHtml':
+        default:
+            // An invisible entity is not a widget, so the builder returns null and it keeps its
+            // literal-source span; anything the registry does not claim falls back the same way,
+            // mirroring the unknown-block fallback so every byte round-trips.
+            container.appendChild(buildCoreInlineWidget(node, raw, opts.buildPortalWidget) ??
+                sourceSpan(raw, node, node.kind === 'entityReference'
+                    ? 'md-entity'
+                    : node.kind === 'rawHtml'
+                        ? 'md-raw-html'
+                        : 'md-unknown-inline'));
+            return null;
+    }
+}
+export function renderInlineNodes(nodes, raw, opts = {}) {
+    // Iterative: nesting depth is input-controlled, so per-level recursion overflows the stack and
+    // strands the block in the unhealable fallback. `scanChildren` is iterative for the same reason.
+    const root = {
+        nodes,
+        index: 0,
+        content: document.createDocumentFragment(),
+        close: null
+    };
+    const stack = [root];
+    while (stack.length > 0) {
+        const frame = stack[stack.length - 1];
+        if (frame.index === frame.nodes.length) {
+            stack.pop();
+            frame.close?.(frame.content);
+            continue;
+        }
+        const child = renderNode(frame.nodes[frame.index++], raw, opts, frame.content);
+        if (child !== null)
+            stack.push(child);
+    }
+    return root.content;
+}
+/**
+ * The leaf containing `offset`, preferring the right node at a boundary; `offset === end` only
+ * matches the last node. Model-layer, touching no DOM: the DOM counterpart is
+ * `findDomTextOffsetTarget` in cursor/widget-offset.ts.
+ */
+export function findNodeAtOffset(nodes, offset) {
+    // Descent never backtracks, the first containing sibling winning its level, so the answer is
+    // the deepest containing node.
+    let level = nodes;
+    let found = null;
+    for (;;) {
+        const node = containingNode(level, offset);
+        if (node === null)
+            return found;
+        found = { node, localOffset: offset - node.start };
+        if (node.children === undefined || node.children.length === 0)
+            return found;
+        level = node.children;
+    }
+}
+/** First node covering `offset`; only the last node claims its own `end`. */
+function containingNode(nodes, offset) {
+    for (let i = 0; i < nodes.length; i++) {
+        const node = nodes[i];
+        const isLast = i === nodes.length - 1;
+        if (offset >= node.start && (offset < node.end || (isLast && offset === node.end)))
+            return node;
+    }
+    return null;
+}

package/dist/core/lines.d.ts

@@ -0,0 +1,44 @@
+/** Line splitting preserving endings and offsets, plus the trailing-line-ending helpers. */
+/** Length of `raw` excluding any trailing line ending (LF or CRLF). */
+export declare function displayLength(raw: string): number;
+export declare function trimTrailingLineEnding(raw: string): string;
+/**
+ * The ending `raw` actually carries — {@link trimTrailingLineEnding}'s complement, the two
+ * partitioning `raw`. What {@link trailingLineEnding} answers instead is which ending the
+ * DOCUMENT uses, so a site reattaching a block's own bytes reads this one (G4.20).
+ */
+export declare function ownTrailingLineEnding(raw: string): '' | '\n' | '\r\n';
+/**
+ * `offset` moved off the interior of a surrogate pair, back to the pair's own start. Caret
+ * offsets are UTF-16 code units, so a cut at one can halve an astral scalar and leave a lone
+ * surrogate — bytes no UTF-8 encoder round-trips (`TextEncoder` yields U+FFFD) and no inverse
+ * gesture restores. Scalars only: a grapheme cluster is a rendering question, and answering it
+ * here would move a caret the author placed between two legitimately separate scalars.
+ */
+export declare function snapToScalarBoundary(raw: string, offset: number): number;
+/**
+ * The block's authored trailing line ending. Every site that reattaches or mints one reads it
+ * here (G4.20), so a CRLF-authored block keeps its ending and an unterminated one gets `\n`.
+ */
+export declare function trailingLineEnding(raw: string): '\n' | '\r\n';
+/**
+ * Keep a truncated slice line-terminated, borrowing `sourceRaw`'s own ending (G4.20). A slice
+ * whose last line stays open swallows whatever follows it once the bytes stand alone.
+ */
+export declare function terminateLine(text: string, sourceRaw: string): string;
+/** Paste entry points funnel through here so Windows CRLF does not leak into a note. */
+export declare function normalizeLineEndings(text: string): string;
+export interface ParsedLine {
+    raw: string;
+    text: string;
+    lineEnding: string;
+    start: number;
+    end: number;
+}
+export declare function splitLines(source: string): ParsedLine[];
+/**
+ * Re-mint a `ParsedLine[]` after a per-line strip, as the container parsers do when they reparse
+ * a prefix-stripped body. Recompute, not spread: reusing an input line's offsets after shortening
+ * its text desyncs the offsets from the bytes.
+ */
+export declare function remapStrippedLines(lines: ParsedLine[], stripLine: (line: ParsedLine, index: number) => string): ParsedLine[];