@llui/lexical-loro 0.1.0

package/dist/order.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Fractional indexing: the sibling ORDER of a child list, as a sortable
+ * property rather than as a list position.
+ *
+ * Every child carrier holds a `pos` string; the rendered order is
+ * `sort by (pos, uuid)` — a PURE function of replicated state, and therefore
+ * commutative by construction. A MOVE is one last-writer-wins register write to
+ * `pos`: no container is deleted, none is recreated, and nothing in the moved
+ * subtree is touched. See `schema.ts` for why that property is load-bearing.
+ *
+ * ── FOUR CONSTRAINTS, EACH MEASURED, EACH EASY TO BREAK ────────────────────
+ *
+ * These are not style preferences. Each one was a REAL, reproduced defect in a
+ * spike, and each is the kind of thing a later contributor removes because it
+ * looks redundant. Do not relax one without re-reading `test/order.test.ts`.
+ *
+ * 1. BATCH ALLOCATION, OFF ONE ANCHOR. Allocating a multi-block paste one block
+ *    at a time makes both peers generate the SAME keys in the same gap, so the
+ *    uuid tiebreak alternates them: two 5-paragraph pastes at the same spot
+ *    render as a 10-paragraph A/B/A/B interleaving. Convergent, and nonsense.
+ *    `allocate` therefore takes the WHOLE batch and hangs it off a single anchor
+ *    carrying a per-peer jitter digit, which confines each peer's paste to a
+ *    private sub-interval.
+ *
+ * 2. JITTER PER BATCH, NEVER PER INSERT. Always-on jitter degrades key growth
+ *    from ~0.2 to ~1.0 characters per insert, because a suffix digit at the far
+ *    end of the alphabet from the direction of travel consumes the whole
+ *    remaining interval. And WHICH digit is pathological is direction-dependent
+ *    — a low digit is worst for repeated left-inserts, a high digit for
+ *    right-inserts — so no fixed per-peer digit is safe in both. `allocate`
+ *    consequently IGNORES `jitter` when `count === 1`, which is the overwhelming
+ *    majority of calls. That branch is not an optimization; deleting it makes
+ *    single-insert keys grow five times faster.
+ *
+ * 3. NEVER REBALANCE. Rewriting every `pos` to spread the keys out evenly is the
+ *    "obvious" fix for key growth. IT IS UNSAFE. A peer that concurrently
+ *    inserted computed its key against the OLD keys, so after the merge its
+ *    block lands at an arbitrary position — convergent, and silently wrong about
+ *    what the user asked for. It is measured: the block ends up at neither of
+ *    the neighbours it was typed between.
+ *
+ *    There is no need for it anyway. Growth is LINEAR and bounded in practice —
+ *    2000 adversarial same-spot inserts reach a 401-character key, and a move
+ *    carries exactly one such key, keeping even that pathological case under a
+ *    kilobyte on the wire. Unlike a plain list's delete+recreate, it does not
+ *    scale with the subtree.
+ *
+ * 4. EQUAL POSITIONS ARE REACHABLE, and the uuid tiebreak only resolves
+ *    RENDERING. Two peers inserting at the same slot mint an IDENTICAL `pos`.
+ *    No key exists strictly between two equal keys, and `between(a, a)` returns
+ *    a key that sorts AFTER BOTH while claiming to sort between them — silent
+ *    corruption of the one invariant this module exists to maintain. Callers
+ *    must go through {@link allocateAt}, which sees the sibling list and widens
+ *    past the degenerate group rather than emitting an impossible key.
+ */
+/**
+ * The key alphabet, in ascending code-unit order.
+ *
+ * Base 62 buys ~5.9 binary subdivisions per character, which is what keeps
+ * growth at roughly one character per five same-spot inserts. Every character
+ * here must be ASCII and strictly ascending, because the comparator is plain
+ * lexicographic `<` on the raw string — the same comparison every peer performs
+ * with no locale involved.
+ */
+export declare const DIGITS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+/**
+ * A key strictly between `a` and `b`, where `null` means unbounded.
+ *
+ * REQUIRES `a < b`. It does not check, and on equal or inverted bounds it
+ * returns a key OUTSIDE the interval rather than failing — see constraint 4.
+ * Prefer {@link allocateAt}, which cannot be called with a degenerate interval.
+ */
+export declare function between(a: string | null, b: string | null): string;
+/**
+ * `count` strictly increasing keys inside the open interval `(before, after)`.
+ *
+ * With `count === 1` the jitter is deliberately ignored (constraint 2). With
+ * `count > 1` the whole batch hangs off ONE anchor carrying the jitter digit, so
+ * two peers' concurrent batches occupy disjoint sub-intervals and cannot
+ * interleave (constraint 1).
+ *
+ * The anchor is a strict extension of a key already strictly below `after`, and
+ * every subsequent key extends the anchor further, so the whole batch stays
+ * inside the interval and in order.
+ */
+export declare function allocate(before: string | null, after: string | null, count: number, jitter: string | null): string[];
+/**
+ * `count` keys placing new children at rendered index `index` among siblings
+ * whose positions are `positions` (ASCENDING — the order the projection
+ * renders).
+ *
+ * This is the only allocation entry point callers should use, because it is the
+ * only one that can see, and therefore honour, constraint 4. When the left
+ * neighbour's position EQUALS the right neighbour's — reachable whenever two
+ * peers insert at the same slot concurrently — there is no key strictly between
+ * them. Rather than emit one that breaks the sort invariant, the right bound is
+ * widened to the first position STRICTLY greater than the left neighbour's, so
+ * the new children land after the whole equal-position group.
+ *
+ * That is a real, if narrow, loss of fidelity: the block lands one slot later
+ * than the user pointed at. It is chosen over the alternatives deliberately —
+ * repositioning the neighbour would be a localized rebalance (constraint 3), and
+ * emitting an out-of-interval key would corrupt the ordering silently.
+ */
+export declare function allocateAt(positions: readonly string[], index: number, count: number, jitter: string | null): string[];
+/**
+ * A stable jitter digit for a peer.
+ *
+ * Takes Loro's own `peerId`, so peers need no coordination to pick distinct
+ * digits. Collisions across the {@link JITTER_DIGITS} alphabet only degrade to
+ * the un-jittered behaviour for the colliding pair; they are not a correctness
+ * problem.
+ */
+export declare function jitterFor(peerId: bigint): string;
+/**
+ * The rendered order of two children: by `pos`, then by `uuid`.
+ *
+ * The uuid tiebreak is what makes this a TOTAL order even when two peers mint
+ * the same `pos`, which is exactly what keeps every peer rendering the same
+ * sequence. It resolves rendering only — it does not make the interval between
+ * two equal positions usable; see constraint 4.
+ */
+export declare function comparePositions(posA: string, uuidA: string, posB: string, uuidB: string): number;
+//# sourceMappingURL=order.d.ts.map

package/dist/order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"order.d.ts","sourceRoot":"","sources":["../src/order.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,MAAM,mEAAmE,CAAA;AAItF;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAQlE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GAAG,IAAI,GACpB,MAAM,EAAE,CAqBV;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CACxB,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GAAG,IAAI,GACpB,MAAM,EAAE,CAgBV;AAWD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAMhD;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAIjG"}

package/dist/order.js

@@ -0,0 +1,187 @@
+/**
+ * Fractional indexing: the sibling ORDER of a child list, as a sortable
+ * property rather than as a list position.
+ *
+ * Every child carrier holds a `pos` string; the rendered order is
+ * `sort by (pos, uuid)` — a PURE function of replicated state, and therefore
+ * commutative by construction. A MOVE is one last-writer-wins register write to
+ * `pos`: no container is deleted, none is recreated, and nothing in the moved
+ * subtree is touched. See `schema.ts` for why that property is load-bearing.
+ *
+ * ── FOUR CONSTRAINTS, EACH MEASURED, EACH EASY TO BREAK ────────────────────
+ *
+ * These are not style preferences. Each one was a REAL, reproduced defect in a
+ * spike, and each is the kind of thing a later contributor removes because it
+ * looks redundant. Do not relax one without re-reading `test/order.test.ts`.
+ *
+ * 1. BATCH ALLOCATION, OFF ONE ANCHOR. Allocating a multi-block paste one block
+ *    at a time makes both peers generate the SAME keys in the same gap, so the
+ *    uuid tiebreak alternates them: two 5-paragraph pastes at the same spot
+ *    render as a 10-paragraph A/B/A/B interleaving. Convergent, and nonsense.
+ *    `allocate` therefore takes the WHOLE batch and hangs it off a single anchor
+ *    carrying a per-peer jitter digit, which confines each peer's paste to a
+ *    private sub-interval.
+ *
+ * 2. JITTER PER BATCH, NEVER PER INSERT. Always-on jitter degrades key growth
+ *    from ~0.2 to ~1.0 characters per insert, because a suffix digit at the far
+ *    end of the alphabet from the direction of travel consumes the whole
+ *    remaining interval. And WHICH digit is pathological is direction-dependent
+ *    — a low digit is worst for repeated left-inserts, a high digit for
+ *    right-inserts — so no fixed per-peer digit is safe in both. `allocate`
+ *    consequently IGNORES `jitter` when `count === 1`, which is the overwhelming
+ *    majority of calls. That branch is not an optimization; deleting it makes
+ *    single-insert keys grow five times faster.
+ *
+ * 3. NEVER REBALANCE. Rewriting every `pos` to spread the keys out evenly is the
+ *    "obvious" fix for key growth. IT IS UNSAFE. A peer that concurrently
+ *    inserted computed its key against the OLD keys, so after the merge its
+ *    block lands at an arbitrary position — convergent, and silently wrong about
+ *    what the user asked for. It is measured: the block ends up at neither of
+ *    the neighbours it was typed between.
+ *
+ *    There is no need for it anyway. Growth is LINEAR and bounded in practice —
+ *    2000 adversarial same-spot inserts reach a 401-character key, and a move
+ *    carries exactly one such key, keeping even that pathological case under a
+ *    kilobyte on the wire. Unlike a plain list's delete+recreate, it does not
+ *    scale with the subtree.
+ *
+ * 4. EQUAL POSITIONS ARE REACHABLE, and the uuid tiebreak only resolves
+ *    RENDERING. Two peers inserting at the same slot mint an IDENTICAL `pos`.
+ *    No key exists strictly between two equal keys, and `between(a, a)` returns
+ *    a key that sorts AFTER BOTH while claiming to sort between them — silent
+ *    corruption of the one invariant this module exists to maintain. Callers
+ *    must go through {@link allocateAt}, which sees the sibling list and widens
+ *    past the degenerate group rather than emitting an impossible key.
+ */
+/**
+ * The key alphabet, in ascending code-unit order.
+ *
+ * Base 62 buys ~5.9 binary subdivisions per character, which is what keeps
+ * growth at roughly one character per five same-spot inserts. Every character
+ * here must be ASCII and strictly ascending, because the comparator is plain
+ * lexicographic `<` on the raw string — the same comparison every peer performs
+ * with no locale involved.
+ */
+export const DIGITS = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+const BASE = DIGITS.length;
+/**
+ * A key strictly between `a` and `b`, where `null` means unbounded.
+ *
+ * REQUIRES `a < b`. It does not check, and on equal or inverted bounds it
+ * returns a key OUTSIDE the interval rather than failing — see constraint 4.
+ * Prefer {@link allocateAt}, which cannot be called with a degenerate interval.
+ */
+export function between(a, b) {
+    let result = '';
+    for (let i = 0;; i++) {
+        const low = a !== null && i < a.length ? DIGITS.indexOf(a[i]) : 0;
+        const high = b !== null && i < b.length ? DIGITS.indexOf(b[i]) : BASE;
+        if (high - low > 1)
+            return result + DIGITS[Math.floor((low + high) / 2)];
+        result += DIGITS[low];
+    }
+}
+/**
+ * `count` strictly increasing keys inside the open interval `(before, after)`.
+ *
+ * With `count === 1` the jitter is deliberately ignored (constraint 2). With
+ * `count > 1` the whole batch hangs off ONE anchor carrying the jitter digit, so
+ * two peers' concurrent batches occupy disjoint sub-intervals and cannot
+ * interleave (constraint 1).
+ *
+ * The anchor is a strict extension of a key already strictly below `after`, and
+ * every subsequent key extends the anchor further, so the whole batch stays
+ * inside the interval and in order.
+ */
+export function allocate(before, after, count, jitter) {
+    if (count <= 0)
+        return [];
+    if (count === 1 || jitter === null) {
+        const keys = [];
+        let previous = before;
+        for (let i = 0; i < count; i++) {
+            const key = between(previous, after);
+            keys.push(key);
+            previous = key;
+        }
+        return keys;
+    }
+    const anchor = between(before, after) + jitter;
+    const keys = [anchor];
+    let suffix = null;
+    for (let i = 1; i < count; i++) {
+        suffix = between(suffix, null);
+        keys.push(anchor + suffix);
+    }
+    return keys;
+}
+/**
+ * `count` keys placing new children at rendered index `index` among siblings
+ * whose positions are `positions` (ASCENDING — the order the projection
+ * renders).
+ *
+ * This is the only allocation entry point callers should use, because it is the
+ * only one that can see, and therefore honour, constraint 4. When the left
+ * neighbour's position EQUALS the right neighbour's — reachable whenever two
+ * peers insert at the same slot concurrently — there is no key strictly between
+ * them. Rather than emit one that breaks the sort invariant, the right bound is
+ * widened to the first position STRICTLY greater than the left neighbour's, so
+ * the new children land after the whole equal-position group.
+ *
+ * That is a real, if narrow, loss of fidelity: the block lands one slot later
+ * than the user pointed at. It is chosen over the alternatives deliberately —
+ * repositioning the neighbour would be a localized rebalance (constraint 3), and
+ * emitting an out-of-interval key would corrupt the ordering silently.
+ */
+export function allocateAt(positions, index, count, jitter) {
+    const clamped = Math.max(0, Math.min(index, positions.length));
+    const before = clamped === 0 ? null : positions[clamped - 1];
+    // `positions` is ascending, so the only degenerate case is EQUALITY, and the
+    // widened bound is the first strictly-greater position at or after `index`.
+    let after = null;
+    for (let i = clamped; i < positions.length; i++) {
+        const candidate = positions[i];
+        if (before === null || candidate > before) {
+            after = candidate;
+            break;
+        }
+    }
+    return allocate(before, after, count, jitter);
+}
+/**
+ * Digits usable as a per-peer jitter suffix.
+ *
+ * `DIGITS[0]` is excluded: appending the lowest digit to an anchor produces a
+ * key that is effectively the anchor itself for subdivision purposes, wasting
+ * the peer-private sub-interval the jitter exists to create.
+ */
+const JITTER_DIGITS = DIGITS.slice(1);
+/**
+ * A stable jitter digit for a peer.
+ *
+ * Takes Loro's own `peerId`, so peers need no coordination to pick distinct
+ * digits. Collisions across the {@link JITTER_DIGITS} alphabet only degrade to
+ * the un-jittered behaviour for the colliding pair; they are not a correctness
+ * problem.
+ */
+export function jitterFor(peerId) {
+    const index = Number(((peerId % BigInt(JITTER_DIGITS.length)) + BigInt(JITTER_DIGITS.length)) %
+        BigInt(JITTER_DIGITS.length));
+    return JITTER_DIGITS[index];
+}
+/**
+ * The rendered order of two children: by `pos`, then by `uuid`.
+ *
+ * The uuid tiebreak is what makes this a TOTAL order even when two peers mint
+ * the same `pos`, which is exactly what keeps every peer rendering the same
+ * sequence. It resolves rendering only — it does not make the interval between
+ * two equal positions usable; see constraint 4.
+ */
+export function comparePositions(posA, uuidA, posB, uuidB) {
+    if (posA !== posB)
+        return posA < posB ? -1 : 1;
+    if (uuidA !== uuidB)
+        return uuidA < uuidB ? -1 : 1;
+    return 0;
+}
+//# sourceMappingURL=order.js.map

package/dist/order.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"order.js","sourceRoot":"","sources":["../src/order.ts"],"names":[],"mappings":"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"}

package/dist/schema.d.ts

@@ -0,0 +1,343 @@
+/**
+ * The Loro container schema that mirrors a Lexical `EditorState`.
+ *
+ * ── Shape ──────────────────────────────────────────────────────────────────
+ *
+ *   doc.getMap('root')                                 // ElementContainer
+ *     'type'     -> string                             // node.getType()
+ *     'props'    -> LoroMap<Record<string, PropValue>> // node props, LWW per key
+ *     'children' -> LoroMap<uuid, ChildCarrier>        // UNORDERED; see below
+ *
+ * Every child is a CARRIER map, keyed in `children` by its own uuid:
+ *
+ *   ChildCarrier = LoroMap {
+ *     'uuid' -> string                 // its own key, duplicated for reading
+ *     'pos'  -> string                 // fractional index; see `order.ts`
+ *     'kind' -> 'element' | 'text'
+ *     // kind === 'element' — the carrier IS the child's ElementContainer:
+ *     'type' -> string
+ *     'props' -> LoroMap
+ *     'children' -> LoroMap<uuid, ChildCarrier>
+ *     // kind === 'text':
+ *     'text' -> LoroText               // created ONCE, never recreated
+ *   }
+ *
+ * Sibling order is NOT a list position. It is `sort by (pos, uuid)` — a pure
+ * function of replicated state, and therefore commutative by construction.
+ *
+ * ── Why fractional indexing, not a LoroMovableList ─────────────────────────
+ *
+ * This schema previously held children in a `LoroMovableList`, whose `move` op
+ * preserves container identity. That property is load-bearing here: ContainerID
+ * is our stable address for a `NodeKey` (see `mapping.ts`), so a child that is
+ * deleted and recreated instead of moved forces its whole subtree to be rebuilt
+ * with fresh NodeKeys — which DISPOSES every mounted `LLuiDecoratorNode` sub-app
+ * in it (`packages/lexical/src/decorator.ts` disposes on the 'destroyed'
+ * mutation). Block drag-reorder is a real operation in this editor.
+ *
+ * `LoroMovableList` was abandoned because loro-crdt 1.13.7 — the LATEST release,
+ * with no upgrade path — has TWO defects in it, both pinned by
+ * `test/loro-upstream.test.ts`:
+ *
+ *  1. A WASM PANIC. Uncatchable from JavaScript, and it leaves the document in
+ *     an unspecified state, so there is no recovery path to write.
+ *  2. A SILENT CONVERGENCE FAILURE — two peers accept the same updates and
+ *     render different documents, with nothing to detect it from.
+ *
+ * A plain `LoroList` plus uuid identity was evaluated and REJECTED: without a
+ * move op, a reorder is delete+recreate, which silently LOSES a peer's
+ * concurrent edit into the moved subtree. Convergent and unrepairable — strictly
+ * worse than the defects it was meant to route around.
+ *
+ * Fractional indexing keeps the property that mattered. A same-parent move is
+ * ONE last-writer-wins register write to `pos` (~87 bytes regardless of subtree
+ * size): no container is deleted, none is created, and every `ContainerID` —
+ * including every `LoroText` — is INVARIANT across reorder, text edits, and
+ * parent moves. So a concurrent edit into a moved subtree survives, and
+ * `mapping.ts` needs no notion of any of this.
+ *
+ * ── What this deliberately does NOT claim ──────────────────────────────────
+ *
+ * Three documented limits. Do not read the paragraph above as covering them:
+ *
+ *  - CROSS-PARENT moves are still delete+recreate, and DO lose a concurrent edit
+ *    into the moved subtree. The "concurrent edit preserved" property is
+ *    SAME-PARENT ONLY. (This is not a regression: `LoroMovableList#move` is also
+ *    confined to a single list.)
+ *  - DELETE BEATS MOVE. A delete concurrent with a move wins and the block
+ *    vanishes, in both delivery orders. Chosen deliberately: `LoroMovableList`
+ *    does the opposite — it RESURRECTS a deliberately deleted block — and pays
+ *    for it with defect 1 above. A tombstone mitigation was tried and REFUTED BY
+ *    TEST (the delete flag and `pos` are different map keys, so both survive and
+ *    nothing is resurrected). Do not re-add tombstones.
+ *  - TWO CONCURRENT SPLITS of the same text run converge on a child COUNT, not
+ *    on sensible text: ordinal text matching mints a fresh tail container on each
+ *    peer, so the merged document duplicates a fragment. Pre-existing — the
+ *    `LoroMovableList` binding produced the same duplication for the same history
+ *    — and out of scope for the ordering model. Verified against real Lexical;
+ *    see `test/convergence-attack.test.ts` for the concurrent-text histories.
+ *
+ * ── Why one LoroText per RUN, not per TextNode ─────────────────────────────
+ *
+ * A RUN is a MAXIMAL GROUP OF ADJACENT `TextNode`s — not one TextNode. That
+ * distinction is the schema's text unit and it is doing real work: Lexical
+ * splits and merges adjacent TextNodes freely (normalization), and a node
+ * boundary is a rendering detail, not user intent. Mirroring nodes 1:1 would
+ * make every normalization a structural CRDT edit and would let two peers'
+ * different-but-equivalent splits conflict.
+ *
+ * The most common "split" is not a structural change at all: bolding a middle
+ * sub-range makes Lexical split one TextNode into THREE, but all three are
+ * adjacent, so they coalesce back to ONE desired child. The carrier count and
+ * the `LoroText` ContainerID are unchanged and the format lands as a mark inside
+ * the existing text. Verified against real Lexical 0.48 by the D1 case in
+ * `test/to-loro.test.ts` ('run identity under Lexical normalization').
+ *
+ * ── Index units ────────────────────────────────────────────────────────────
+ *
+ * loro-crdt's JavaScript binding addresses `LoroText` in UTF-16 code units —
+ * the same unit as JavaScript string indices and therefore the same unit as
+ * Lexical offsets. NO conversion is required at this seam. (`convertPos` exists
+ * for unicode/utf8 interop; we never need it.) This is pinned by a test in
+ * `test/schema.test.ts` because it is an assumption the whole binding rests on
+ * and it is not stated in loro-crdt's type declarations.
+ */
+import { LoroMap, LoroText } from 'loro-crdt';
+import type { Container, ContainerID, LoroDoc } from 'loro-crdt';
+/** Root map name on the `LoroDoc`. Mirrors Lexical's `RootNode`. */
+export declare const ROOT_CONTAINER = "root";
+/** Key on an element map holding the Lexical node type (`node.getType()`). */
+export declare const KEY_TYPE = "type";
+/** Key on an element map holding the scalar-prop sub-map. */
+export declare const KEY_PROPS = "props";
+/** Key on an element map holding the child-carrier map. */
+export declare const KEY_CHILDREN = "children";
+/**
+ * Key on a child carrier holding its own uuid.
+ *
+ * Duplicated from the `children` map key so a carrier read in isolation still
+ * knows its identity, and so the ordering tiebreak needs no parent lookup.
+ */
+export declare const KEY_UUID = "uuid";
+/** Key on a child carrier holding its fractional index. See `order.ts`. */
+export declare const KEY_POS = "pos";
+/**
+ * Key on a child carrier discriminating an element from a text run.
+ *
+ * Explicit rather than inferred from which other keys are present: a remote
+ * update can be applied partially, and a carrier whose `type` has not landed yet
+ * must be SKIPPED by the projection, not mistaken for a text run.
+ */
+export declare const KEY_KIND = "kind";
+/** Key on a TEXT carrier holding its `LoroText`. */
+export declare const KEY_TEXT = "text";
+/**
+ * `type` value used for an `LLuiDecoratorNode`. Its identity lives in
+ * `props.bridgeType`; its serialized payload in `props.data`.
+ */
+export declare const DECORATOR_TYPE = "llui-decorator";
+/** `props` key naming which LLui bridge renders a decorator. */
+export declare const KEY_BRIDGE_TYPE = "bridgeType";
+/** `props` key holding a decorator's JSON-serialized payload. */
+export declare const KEY_DATA = "data";
+/**
+ * A value storable in an element's `props` map: any JSON value.
+ *
+ * Most Lexical node props are scalars (`tag`, `format`, `indent`, …), but not
+ * all — `LLuiDecoratorNode.exportJSON()` emits `data: unknown`, an arbitrary
+ * JSON payload, and that payload is precisely what makes a decorator's mounted
+ * LLui sub-app reproducible on a peer. Loro stores a JSON value in a map slot as
+ * ONE last-writer-wins register, which is the same granularity a scalar gets, so
+ * widening the type costs nothing structurally.
+ *
+ * The LWW granularity is per KEY, not per nested field: two peers editing
+ * different fields of the same `data` object do not merge, the later write wins
+ * whole. Decorator payloads are small, opaque-to-us blobs, so that is the right
+ * trade; a decorator wanting field-level merging should model its state as its
+ * own Loro container rather than as a prop.
+ */
+export type PropValue = string | number | boolean | null | PropValue[] | {
+    [key: string]: PropValue;
+};
+/** An element's prop map. Each key is independently last-writer-wins. */
+export type PropsContainer = LoroMap<Record<string, PropValue>>;
+/**
+ * The map mirroring one Lexical `ElementNode` (or a `DecoratorNode` /
+ * `LineBreakNode`, which simply carry an empty `children` map).
+ *
+ * Every element except the ROOT is also a child carrier, so it additionally
+ * holds `uuid`, `pos` and `kind`. The root is reached through `doc.getMap` and
+ * has no siblings to be ordered among, so those keys are optional.
+ */
+export type ElementContainer = LoroMap<ElementShape>;
+/** An element map's key set. */
+export interface ElementShape extends Record<string, unknown> {
+    [KEY_TYPE]: string;
+    [KEY_PROPS]: PropsContainer;
+    [KEY_CHILDREN]: ChildrenContainer;
+}
+/** What a child carrier wraps. */
+export type ChildKind = 'element' | 'text';
+/** A carrier holding one text run's `LoroText`. */
+export type TextCarrier = LoroMap<TextCarrierShape>;
+/** A text carrier's key set. */
+export interface TextCarrierShape extends Record<string, unknown> {
+    [KEY_UUID]: string;
+    [KEY_POS]: string;
+    [KEY_KIND]: 'text';
+    [KEY_TEXT]: LoroText;
+}
+/**
+ * An element's children, keyed by uuid. UNORDERED — the rendered sequence comes
+ * from {@link orderedChildren}, never from iteration order.
+ */
+export type ChildrenContainer = LoroMap<Record<string, ChildCarrier>>;
+/**
+ * The keys EVERY child carrier holds, whatever it wraps.
+ *
+ * Typed as its own shape rather than as `ElementContainer | TextCarrier` so that
+ * the ordering keys can be written without narrowing: a union of two generic
+ * `LoroMap` signatures is not callable, and the position write is the one
+ * operation that is genuinely common to both kinds.
+ */
+export interface CarrierShape extends Record<string, unknown> {
+    [KEY_UUID]: string;
+    [KEY_POS]: string;
+    [KEY_KIND]: ChildKind;
+}
+/** A carrier sitting in a `children` map, seen through its common keys. */
+export type ChildCarrier = LoroMap<CarrierShape>;
+/**
+ * The container a child's IDENTITY is registered under in `mapping.ts`: the
+ * `LoroText` for a text run, the element map itself for an element.
+ *
+ * Both are invariant across every reorder, which is what lets the registry stay
+ * ignorant of the ordering model entirely.
+ */
+export type ChildContainer = ElementContainer | LoroText;
+/** One child of an element, as the ordering projection sees it. */
+export interface ChildEntry {
+    readonly uuid: string;
+    readonly pos: string;
+    readonly kind: ChildKind;
+    /** The carrier map. For an element child this IS its {@link ElementContainer}. */
+    readonly carrier: ChildCarrier;
+    /** The container this child is addressed by. See {@link ChildContainer}. */
+    readonly container: ChildContainer;
+}
+/** Loro's per-mark conflict-resolution rule. */
+export type ExpandType = 'before' | 'after' | 'none' | 'both';
+/**
+ * The `expand` rule applied UNIFORMLY to every text format.
+ *
+ * Read `test/expand-semantics.test.ts` before changing this. `expand` is NOT
+ * the mechanism that reproduces Lexical's boundary behaviour — a 51-test spike
+ * proved no uniform table can, and that no per-format table can either (the
+ * divergence set is identical for all 11 formats, because Lexical has no
+ * per-format inclusivity: its caret is uniformly left-biased). The Lexical→Loro
+ * direction replays RESULTING NODE STATE via explicit mark/unmark ops instead
+ * (see `diffRunFormats` in `text.ts`), which makes the local result correct
+ * regardless of `expand`.
+ *
+ * `expand` therefore governs exactly one thing: what happens to text a REMOTE
+ * peer inserts CONCURRENTLY at a mark boundary. `'after'` is the closest fit to
+ * Lexical's left-biased caret.
+ */
+export declare const TEXT_MARK_EXPAND: ExpandType;
+/** The Lexical node type of the root. Matches `RootNode.getType()`. */
+export declare const ROOT_TYPE = "root";
+/**
+ * Configure a `LoroDoc` for this schema and return its root element container,
+ * creating the root's schema keys if they are missing.
+ *
+ * Every peer MUST call this. Two reasons, both load-bearing:
+ *
+ * 1. `configTextStyle` is LOCAL configuration, not replicated state. A peer that
+ *    skips it resolves marks under different expand rules and diverges.
+ * 2. The root's `props`/`children` are created with `ensureMergeable*`, which
+ *    derives a DETERMINISTIC ContainerID from the parent and key. Two peers may
+ *    each initialize an empty document before ever hearing from one another; a
+ *    plain `setContainer` would mint two different child containers and the map
+ *    slot's last-writer-wins would silently discard one peer's entire document.
+ *    `ensureMergeable*` makes both peers land on the same container, so their
+ *    edits merge. (Only the ROOT needs this — every other element is created
+ *    whole by a single peer and inserted as one op.)
+ */
+export declare function initDoc(doc: LoroDoc, formats: readonly string[]): ElementContainer;
+/**
+ * A fresh child identity.
+ *
+ * MUST be random. Two peers minting the same uuid would collide on one slot of
+ * the `children` map, whose last-writer-wins would silently discard a whole
+ * block — the same class of data loss `initDoc`'s `ensureMergeable*` exists to
+ * prevent for the root.
+ */
+export declare function newUuid(): string;
+/**
+ * Create an element child inside `children` and return its ATTACHED container.
+ *
+ * The carrier IS the element container: an element needs a `pos` anyway, so
+ * wrapping it in a second map would cost an extra container and an extra
+ * dereference for nothing. Only the attached handle has a stable `ContainerID`,
+ * so always take identity from what this returns.
+ */
+export declare function createElementChild(children: ChildrenContainer, uuid: string, pos: string, type: string): ElementContainer;
+/**
+ * Create a text child inside `children` and return its ATTACHED `LoroText`.
+ *
+ * The `LoroText` is created once, inside its carrier, and never moved or
+ * recreated — which is precisely what makes its `ContainerID` invariant across
+ * every reorder, and therefore what lets a peer's concurrent insertion into it
+ * survive a block move.
+ */
+export declare function createTextChild(children: ChildrenContainer, uuid: string, pos: string): LoroText;
+/** Re-position a child — the whole cost of a same-parent move. */
+export declare function setChildPosition(carrier: ChildCarrier, pos: string): void;
+/** Remove a child from its parent, container and all. */
+export declare function deleteChild(children: ChildrenContainer, uuid: string): void;
+/**
+ * An element's children in RENDERED order: sorted by `(pos, uuid)`.
+ *
+ * Malformed carriers are SKIPPED rather than thrown on. That is not defensive
+ * padding: a remote update can be applied while a carrier's keys are still
+ * arriving, and a partially-materialized child must not crash a render — it will
+ * appear on the next event, once its `pos` and `kind` have landed.
+ *
+ * Nothing here consults `isDeleted()`, and nothing may. Projection must depend
+ * ONLY on replicated state; a deleted carrier is simply absent from `keys()` on
+ * every peer, which is what makes this a pure function of the document.
+ */
+export declare function orderedChildren(element: ElementContainer): ChildEntry[];
+/** How many well-formed children an element has. */
+export declare function childCount(element: ElementContainer): number;
+/** Read an element's Lexical node type. */
+export declare function elementType(element: ElementContainer): string;
+/** Read an element's scalar-prop map. */
+export declare function elementProps(element: ElementContainer): PropsContainer;
+/** Read an element's child-carrier map. UNORDERED — see {@link orderedChildren}. */
+export declare function elementChildren(element: ElementContainer): ChildrenContainer;
+/** Narrow a child slot to an element container. */
+export declare function isElementContainer(child: unknown): child is ElementContainer;
+/** Narrow a child slot to a text run. */
+export declare function isTextContainer(child: unknown): child is LoroText;
+/** True when this element mirrors an `LLuiDecoratorNode`. */
+export declare function isDecoratorElement(element: ElementContainer): boolean;
+/**
+ * Whether a container still exists in the document.
+ *
+ * `getContainerById` keeps returning a usable handle for a DELETED container, so
+ * `isDeleted()` is the real test. The kind narrowing is not defensive padding:
+ * `Container` includes `LoroCounter`, `LoroList` and `LoroTree`, which this
+ * schema never uses, and only its two kinds may enter the registry.
+ *
+ * This is a LOCAL liveness question — "is the registry entry stale?" — not a
+ * projection question. See {@link orderedChildren}.
+ */
+export declare function containerIsLive(doc: LoroDoc, id: ContainerID): boolean;
+/**
+ * The `ContainerID` of an attached container — the STABLE, cross-peer address
+ * this binding maps to a per-session `NodeKey`. Throws on a detached container,
+ * which has no replicated identity and must never enter the mapping.
+ */
+export declare function containerId(container: Container): ContainerID;
+//# sourceMappingURL=schema.d.ts.map