edytor 3.0.0 → 5.0.0

package/dist/crdt/doc/steps.d.ts

@@ -1,28 +1,40 @@
+/**
+ * The step writers every prepared op composes: the plan itself, moves (a
+ * move's place and side), type steps and the kind a block shows where it
+ * lands (`settle`), the containers and layouts a write leaves empty
+ * (`emptying`, `dissolving`), delete and merge steps, and display spans of a
+ * block's content.
+ */
 import { TYPE } from '../schema.js';
 import { type BlockId, type ContentItem } from '../placement/model.js';
 import type { Plan, PlanStep } from './types.js';
 import type { DocBase, DocReads } from './reads.js';
 import type { DocCapability } from './capability.js';
 /** What the step writers read: the reads and the structural capability. */
+/**
+ * A record's order among the records standing at one block, for the
+ * engine's sort of two records at one origin (fork patch YP22): what a split
+ * of a list around a block writes there — a new head list holding the items
+ * before it (`head`), new blocks placed after the items before it, which
+ * stay (`kept`), a head holding those items and the block (`with`), the
+ * block itself leaving (`self`), new blocks after it (`after`) — in the
+ * order every serial run of the gestures gives (`del.merge.container`).
+ */
+export declare const PART: {
+    readonly head: 0;
+    readonly kept: 1;
+    readonly with: 2;
+    readonly self: 3;
+    readonly after: 4;
+};
 export type StepsContext = DocBase & DocReads & DocCapability;
 /** The step writers of one facade. */
 export declare const planSteps: (c: StepsContext) => {
     REFUSED: import("./types.js").OpResult;
-    HEAD: number;
-    KEPT: number;
-    WITH: number;
-    SELF: number;
-    AFTER: number;
     plan: (ids: readonly BlockId[], writes: PlanStep[]) => Plan;
-    ranksFor: (parent: BlockId | null, index: number, count: number, exclude?: readonly BlockId[], run?: boolean) => string[];
-    moveTo: (ids: BlockId[], parent: BlockId | null, index: number, ranks: string[]) => PlanStep[];
+    moveTo: (ids: BlockId[], parent: BlockId | null, index: number, side?: 0 | 1, at?: BlockId, part?: number) => PlanStep[];
     move: (ids: BlockId[], parent: BlockId | null, index: number) => PlanStep[];
-    exitRanks: (outer: BlockId, after: boolean, parts: readonly {
-        at: BlockId;
-        part: readonly number[];
-    }[]) => string[];
-    pieceRanks: (id: BlockId, at: number, count: number) => string[];
-    leaving: (outer: BlockId, after: boolean, ids: readonly BlockId[]) => string[];
+    leaving: (after: boolean) => 0 | 1;
     attr: (id: BlockId, key: typeof TYPE, value: string) => PlanStep[];
     leavingIsland: (island: BlockId, kind: string | undefined, to: string) => string | undefined;
     settledKind: (from: BlockId | null, kid: BlockId, parent: BlockId | null) => string | undefined;

package/dist/crdt/doc/steps.js

@@ -1,17 +1,27 @@
 /**
- * The step writers every prepared op composes: the plan itself, ranks (a
- * move's, a source rank by where blocks come from, a split's pieces), type
- * steps and the kind a block shows where it lands (`settle`), the
- * containers and layouts a write leaves empty (`emptying`, `dissolving`),
- * delete and merge steps, and display spans of a block's content.
+ * The step writers every prepared op composes: the plan itself, moves (a
+ * move's place and side), type steps and the kind a block shows where it
+ * lands (`settle`), the containers and layouts a write leaves empty
+ * (`emptying`, `dissolving`), delete and merge steps, and display spans of a
+ * block's content.
  */
-import { randOf } from '../rand.js';
 import { TYPE } from '../schema.js';
-import { blockNodeOf, positionInView, promotedRank, ranksAt, SOURCE_SIDE, sourceRank } from '../placement/model.js';
+import { blockNodeOf } from '../placement/model.js';
 import { REFUSED, effectOf } from './plan.js';
+/** What the step writers read: the reads and the structural capability. */
+/**
+ * A record's order among the records standing at one block, for the
+ * engine's sort of two records at one origin (fork patch YP22): what a split
+ * of a list around a block writes there — a new head list holding the items
+ * before it (`head`), new blocks placed after the items before it, which
+ * stay (`kept`), a head holding those items and the block (`with`), the
+ * block itself leaving (`self`), new blocks after it (`after`) — in the
+ * order every serial run of the gestures gives (`del.merge.container`).
+ */
+export const PART = { head: 0, kept: 1, with: 2, self: 3, after: 4 };
 /** The step writers of one facade. */
 export const planSteps = (c) => {
-    const { doc, runsView, roles, rendersContentOf, view, blockTypeOf, childrenIds, positionOf, ancestorsOf, is, isIsland, itemKindOf, isLayout, displayLength, contentItems, live, isContainer, fitted, emptiable, rendersContent, defaultChild } = c;
+    const { doc, runsView, roles, view, blockTypeOf, childrenIds, positionOf, ancestorsOf, isLines, isIsland, itemKindOf, isLayout, displayLength, contentItems, live, isContainer, fitted, emptiable, defaultChild } = c;
     // ── prepared ops ─────────────────────────────────────────────
     // Every op is `prepare` (pure: `refused`, or a plan of named steps plus
     // its effect summary, against the current version) then `apply(plan)`;
@@ -19,124 +29,52 @@ export const planSteps = (c) => {
     // whole command before any write and a refusal refuses before one.
     // Each prepare normalizes its inputs once, here at ingress: ids
     // and strings as the wire would deliver them, payloads cloned.
-    /** `exitRanks` parts, in their order at one block. */
-    const [HEAD, KEPT, WITH, SELF, AFTER] = [0, 1, 2, 3, 5];
     const plan = (ids, writes) => ({
         ids,
         writes,
         effect: effectOf(writes),
         version: runsView.version()
     });
-    /** This client's next clock: what its source ranks are tied by (`sourceRank`). */
-    const clock = () => doc.store?.getClock(doc.clientID) ?? 0;
-    /**
-     * `count` ranks at `index` among `parent`'s children, the moving
-     * `exclude` left out. `run`: new blocks, which extend this client's run
-     * after a block it ranked (`order.insert.run`); a move never does
-     * (the rank-growth guard).
-     */
-    const ranksFor = (parent, index, count, exclude = [], run = false) => {
-        const v = view();
-        const all = v.kids.get(parent) ?? [];
-        // The moving blocks' own slots left out: index → the list's index past them.
-        const gone = exclude
-            .map((id) => positionInView(v, id))
-            .filter((p) => p !== null && p.parent === parent)
-            .map((p) => p.index)
-            .sort((a, b) => a - b);
-        const raw = (i) => {
-            for (const g of gone)
-                if (g <= i)
-                    i++;
-            return i;
-        };
-        const at = Math.max(0, Math.min(index, all.length - gone.length));
-        const pair = [at > 0 ? all[raw(at - 1)] : undefined, all[raw(at)]];
-        return ranksAt(pair, 1, count, doc.clientID, randOf(doc), run);
-    };
     /**
-     * Move `ids` to `ranks` under `parent` (`index`: the slot hooks see).
+     * Move `ids` to display index `index` among `parent`'s children (the
+     * slot hooks see). `side`: the move record's class among the items of
+     * its origin (`placement/slots.ts`) — `0`, the blocks stand after what
+     * precedes them (a move; blocks leaving a block for the gap after it:
+     * its children, a list's last items); `1`, before what follows them
+     * (blocks leaving a block for the gap before it: a list's first item
+     * lifted out). In one gap every serial order of the gestures puts a
+     * split's pieces first, then the after-records, then the before-records
+     * (`del.merge.container`), which the engine's sort gives whatever the
+     * client ids.
      * Every planned move carries the type steps that keep what the moved
      * blocks show: one displayed out of an island as another kind than its
      * stored one (`displayType`) gets that kind written, so leaving the
      * island's slot never brings the island's child kind back.
+     * `at`, `part`: the block the record stands at and its order among the
+     * records standing there, for the engine's sort of two records at one
+     * origin (`PART`; by default the first moved block, as itself).
      */
-    const moveTo = (ids, parent, index, ranks) => ids.length === 0
+    const moveTo = (ids, parent, index, side = 0, at, part) => ids.length === 0
         ? []
         : [
-            { op: 'moveBlocks', ids, parent, index, ranks },
+            {
+                op: 'moveBlocks',
+                ids,
+                parent,
+                index,
+                ...(side === 1 && { side }),
+                ...(at !== undefined && { at }),
+                ...(part !== undefined && { part })
+            },
             ...ids.flatMap((id) => {
                 const shown = runsView.displayType(id);
                 return shown === undefined ? [] : attr(id, TYPE, shown);
             })
         ];
     /** Move `ids` to `index` among `parent`'s children. */
-    const move = (ids, parent, index) => moveTo(ids, parent, index, ranksFor(parent, index, ids.length, ids));
-    /**
-     * Ranks for blocks leaving `outer` for the gap right before it (`after`:
-     * right after it), in the order they come from (`sourceRank`):
-     * two peers that split or lift out of the same list at once keep the
-     * text in its order, whatever their client ids. Each part names the
-     * block in `outer` it stands at (`at`; one that shows no text of its
-     * own, a list, stands at its first item) and its `part` there:
-     * - `HEAD`: a new list holding the items before `at`;
-     * - `KEPT`, index: a block placed after the items before `at`, which
-     *   stay (a divider inserted after an item: a peer's head that takes
-     *   them sorts before it);
-     * - `WITH`: a new list holding the items before `at` and `at` (`keep`);
-     * - `SELF`: `at` itself leaving (`SELF + 1` when it stands at its first item);
-     * - `AFTER`, index: a block placed after it.
-     * A degenerate gap ranks them as any insert.
-     */
-    const exitRanks = (outer, after, parts) => {
-        const { kids } = view();
-        const { parent, index } = positionOf(outer);
-        const sibs = kids.get(parent) ?? [];
-        const gap = after ? index + 1 : index;
-        const ranks = [];
-        for (let { at, part } of parts) {
-            const own = at;
-            while (!rendersContent(at) && childrenIds(at).length > 0)
-                at = childrenIds(at)[0];
-            if (part[0] === SELF && at !== own)
-                part = [SELF + 1];
-            const path = [];
-            for (let c = at; c !== outer; c = positionOf(c).parent) {
-                const pos = positionOf(c);
-                path.unshift(kids.get(pos.parent)[pos.index].rank);
-            }
-            const side = after ? SOURCE_SIDE.after : SOURCE_SIDE.before;
-            const rank = sourceRank(sibs[gap - 1]?.rank, sibs[gap]?.rank, side, path, part, doc.clientID, clock());
-            if (rank === null)
-                return ranksFor(parent, gap, parts.length);
-            ranks.push(rank);
-        }
-        return ranks;
-    };
-    /**
-     * Ranks for the `count` blocks a split of `id` at `at` puts right after
-     * it (Enter, a paste of several lines), by where it splits
-     * (SW12-crdt-1, SW12-crdt-4): two peers splitting one block at once
-     * keep its pieces in text order, whatever their client ids. Counted
-     * from the end — the text after the split point, most first — so a
-     * peer's own edit before its split point (typing, then Enter; a paste
-     * over a selection) does not move it; an unseen edit after
-     * it does (the residual, in the delete contract).
-     */
-    const pieceRanks = (id, at, count) => {
-        const { parent, index } = positionOf(id);
-        const sibs = view().kids.get(parent) ?? [];
-        const ranks = [];
-        for (let i = 0; i < count; i++) {
-            const rank = sourceRank(sibs[index]?.rank, sibs[index + 1]?.rank, SOURCE_SIDE.pieces, [], [at - displayLength(id), i], doc.clientID, clock());
-            if (rank === null)
-                return ranksFor(parent, index + 1, count);
-            ranks.push(rank);
-        }
-        return ranks;
-    };
-    /** `exitRanks` for `ids` themselves leaving `outer`. */
-    const leaving = (outer, after, ids) => exitRanks(outer, after, ids.map((at) => ({ at, part: [SELF] })));
+    const move = (ids, parent, index) => moveTo(ids, parent, index);
+    /** The side of blocks leaving a block for the gap right after it (`after`) or right before it. */
+    const leaving = (after) => (after ? 0 : 1);
     /**
      * A type step, planned only when the kind differs (the one same-value
      * guard). A kind counts as the same only when the block is stored and
@@ -176,9 +114,9 @@ export const planSteps = (c) => {
      * default kind, any other child keeps its kind (as `typeOf`).
      */
     const leavingIsland = (island, kind, to) => {
-        if (rendersContentOf(to) || (kind !== undefined && !rendersContentOf(kind)))
+        if (roles.of(to).rendersContent || (kind !== undefined && !roles.of(kind).rendersContent))
             return to;
-        return is(island, (type) => roles.line(type) !== undefined) ? defaultChild(null) : kind;
+        return isLines(island) ? defaultChild(null) : kind;
     };
     const settledKind = (from, kid, parent) => {
         let kind = blockTypeOf(kid);
@@ -191,7 +129,7 @@ export const planSteps = (c) => {
             // column's default child is the document's: it holds no items of its own.
             const outer = kind !== defaultChild(null) &&
                 within.some((a) => isContainer(a) && defaultChild(a) === kind);
-            if (!outer && rendersContentOf(to))
+            if (!outer && roles.of(to).rendersContent)
                 kind = to;
         }
         return fitted(parent, kind);
@@ -241,10 +179,10 @@ export const planSteps = (c) => {
      * with one item or none — `gone` (blocks the plan removes) and
      * `leaving` (blocks it moves) no longer count, an item `writes` move or
      * insert into it does. With one left, the layout and that item are
-     * deleted and the item's children moved to the layout's slot at the
-     * rank `layout.single` reads (`promotedRank` of the layout's, then the
-     * item's), as the kind they show there (`settle`); with none, the
-     * layout is deleted. One plan with the write that caused it.
+     * deleted and the item's children moved right after the layout, where
+     * `layout.single` shows them, as the kind they show there (`settle`);
+     * with none, the layout is deleted. One plan with the write that caused
+     * it.
      */
     const dissolving = (gone, leaving, writes) => {
         const away = new Set([...gone, ...leaving]);
@@ -269,17 +207,17 @@ export const planSteps = (c) => {
             const items = slots.filter((k) => !away.has(k.id) && blockTypeOf(k.id) === item);
             if (items.length + arriving > 1)
                 continue;
-            const { parent, index } = positionOf(layout);
-            const rank = kids.get(parent)[index].rank;
+            const { parent } = positionOf(layout);
             const last = items[0];
             if (last === undefined) {
                 out.push(deleting(layout, [layout]));
                 continue;
             }
+            // Its blocks keep their home slots: the read shows them in the layout's
+            // slot (`layout.single`), settled for its parent.
             const moved = (kids.get(last.id) ?? []).filter((k) => !away.has(k.id));
             const ids = moved.map((k) => k.id);
-            const ranks = moved.map((k) => promotedRank(rank, promotedRank(last.rank, k.rank)));
-            out.push(...moveTo(ids, parent, index + 1, ranks), ...settle(last.id, ids, parent), deleting(layout, [layout, last.id]));
+            out.push(...settle(last.id, ids, parent), deleting(layout, [layout, last.id]));
         }
         return out;
     };
@@ -349,17 +287,9 @@ export const planSteps = (c) => {
     const emptied = (leaving, writes, kept) => emptyingAll(leaving.map((id) => positionOf(id).parent), leaving, writes, kept);
     return {
         REFUSED,
-        HEAD,
-        KEPT,
-        WITH,
-        SELF,
-        AFTER,
         plan,
-        ranksFor,
         moveTo,
         move,
-        exitRanks,
-        pieceRanks,
         leaving,
         attr,
         leavingIsland,

package/dist/crdt/doc/suggest.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Shared suggestions (`docs/archive/shared-suggestions/design.md`, the
+ * `sugg.*` rows of `docs/editor-delete-contract.md`): a suggestion lives in
+ * the document, so every replica, the room and a reload see it.
+ *
+ * - A suggestion is a record node under the root `suggest`, written by its
+ *   **writer**: a client id minted for a suggesting session, bound to its
+ *   author with its first write like any replica. The record's own item
+ *   opens the writer's clocks it owns, up to the writer's next record; its
+ *   creation is in no history step, so no undo or redo moves them.
+ * - **An insertion** is the writer's own text and blocks: a shown unit or
+ *   block of the writer, in the record's clocks, not settled, is pending.
+ * - **A deletion** writes nothing to the text: the writer's id list (fork
+ *   patch YP31, a hold record that holds nothing inside a nested node) in
+ *   the record names the units; a shown one, not settled, is pending. A
+ *   block deletion is the same id list naming the block's node.
+ * - Nothing else is suggested: a move, a merge, a retype, a data change or
+ *   a format is refused (written directly on its author's own pending
+ *   block).
+ * - **A decision** writes only what changes, one engine call over the
+ *   change's ids (`YNode#hold`): the text that goes is the reviewer's hold
+ *   (fork patch YP20, the root records list), the text that stays a settled
+ *   id list written by the reviewer into the record (its client is the
+ *   decider).
+ *
+ * What is pending is a function of the replicated state (items, records,
+ * settled ranges), so replicas converge in any delivery order. It is read
+ * again after any write, from the blocks the records' writers and
+ * proposals are in: a document with no suggestion pays nothing.
+ *
+ * The part is built over a document by {@link suggestionsOf} (the shared
+ * suggestions plugin, the room, a bare document on a server): once built,
+ * the document's `toJSON()` leaves its pending suggestions out. A document
+ * no one built it over reads its suggestions' content as plain content.
+ */
+import type { EngineDoc } from '../engine-api.js';
+import { type BlockId } from '../placement/model.js';
+import type { DocAnchor, EdytorDocConfig, OpResult, Prepared } from './types.js';
+import type { DocBase, DocReads } from './reads.js';
+import type { JSONDoc } from '../../utils/json.js';
+import type { EdytorDocument } from '../document.js';
+/** One change of a suggestion, as a reviewer sees it. */
+export type SuggestedChange = {
+    /** The suggestion it is part of (its record's id). */
+    readonly suggestion: string;
+    /**
+     * `insert`: a run of text it inserts; `delete`: a run it proposes to
+     * delete; `block`: a block it inserts, its text with it; `split`: the
+     * block its split makes; `remove`: a block it proposes to delete.
+     */
+    readonly kind: 'insert' | 'delete' | 'block' | 'split' | 'remove';
+    /** The block it is in or about. */
+    readonly block: BlockId;
+    /** Its run, in the block's display offsets (a block's: the whole block). */
+    readonly offset: number;
+    readonly length: number;
+    readonly text: string;
+};
+/** A suggestion the document holds. */
+export type SuggestionRecord = {
+    readonly id: string;
+    /** Its author (its writer's actor), `undefined` until the binding arrives. */
+    readonly by: string | undefined;
+    /** The agent that wrote it for its author (`'ai'`), when one did. */
+    readonly via: string | undefined;
+    readonly label: string | undefined;
+    /** When it was opened (ms since the epoch). */
+    readonly at: number;
+};
+/**
+ * One part of a decision: an id list written into suggestion `into`'s
+ * record (settled: it stays) or, `into` null, the decider's hold of the
+ * text that goes (fork patch YP20, the root records list): one engine
+ * call either way (`YNode#hold`); or a document operation's calls (their
+ * arguments read when it runs).
+ */
+export type DecisionPart = {
+    into: string | null;
+    ids: number[];
+    blocks?: BlockId[];
+} | {
+    op: string;
+    calls: () => unknown[][];
+};
+/** What the part reads of its document beyond the facade: the facade's `part` (`edytor-doc.ts`). */
+export type SuggestContext = DocBase & DocReads & {
+    config: EdytorDocConfig;
+    /** A facade over another doc, with `config`. */
+    create: (doc: EngineDoc, config: EdytorDocConfig) => SuggestFacade;
+    /** Its changes no index fact shows: counted in the facade's `version`. */
+    v: number;
+    /** The export `toJSON()` gives unless asked for the suggestions. */
+    base: (() => JSONDoc | undefined) | undefined;
+};
+/** The facade the part is built over: its `part`, and the operations it writes through. */
+export type SuggestFacade = {
+    part: SuggestContext;
+    toJSON: (options?: {
+        suggestions?: boolean;
+    }) => JSONDoc;
+    dispose: () => void;
+    apply: (p: Prepared, quiet?: boolean) => OpResult;
+    transact: <R>(fn: () => R) => R;
+    anchorAt: (id: BlockId, offset: number, affinity?: 'left' | 'right') => DocAnchor | null;
+    resolveAnchor: (anchor: DocAnchor) => {
+        blockId: BlockId;
+        offset: number;
+    } | null;
+    /** Its operations by name (`f[op](…args)`). */
+    [op: string]: unknown;
+};
+/**
+ * The shared suggestions of the document `facade` is over, built once:
+ * from then on, its `toJSON()` leaves the pending ones out (`sugg.json.base`).
+ */
+export declare const suggestionsOf: (facade: SuggestFacade) => DocSuggest;
+/**
+ * Build the shared suggestions over `document`, a document read without a
+ * view (on a server, in a worker): its `toJSON()` leaves the pending ones
+ * out from then on, as a view's with the shared suggestions plugin does. A
+ * document no one built them over reads their content as plain content.
+ */
+export declare const adoptSharedSuggestions: (document: EdytorDocument) => void;
+/** The document's shared suggestions ({@link suggestionsOf}), built over facade `f`. */
+declare const docSuggest: (f: SuggestFacade) => {
+    /** A fresh writer this replica writes suggestions under. */
+    writer: () => number;
+    /** The writers this replica minted (a history tags their steps, `StackItem.writer`). */
+    writers: Set<number>;
+    open: (options?: {
+        id?: string;
+        writer?: number;
+        via?: string;
+        label?: string;
+        at?: number;
+    }) => string;
+    apply: (id: string | null, p: Prepared, w?: number) => {
+        result: OpResult;
+        id?: string;
+        at?: {
+            block: BlockId;
+            offset: number;
+        };
+    };
+    decide: (changes: readonly SuggestedChange[], accept: boolean) => DecisionPart[];
+    run: (parts: readonly DecisionPart[], exec?: (op: string, args: unknown[]) => unknown, w?: number) => void;
+    /** The suggestions the document holds, oldest first. */
+    records: () => SuggestionRecord[];
+    /** Whether the document holds any suggestion record. */
+    any: () => boolean;
+    /** Every pending change, in document order. */
+    changes: () => SuggestedChange[];
+    /** The pending changes of block `b` (`[]`: none). */
+    at: (b: BlockId) => readonly SuggestedChange[];
+    /** Bumped by every change of the records. */
+    version: () => number;
+    /** Be told of every change of the records. Returns the unsubscribe. */
+    onChange: (f: () => void) => () => undefined;
+    /** @internal The work done (blocks read, units walked): the scaling rows count it. */
+    debug: {
+        computes: number;
+        units: number;
+    };
+    dispose: () => void;
+};
+export type DocSuggest = ReturnType<typeof docSuggest>;
+export {};