edytor 4.0.0 → 5.0.0

package/dist/crdt/text/model.d.ts

@@ -277,6 +277,16 @@ export declare const insertIntoText: (doc: EngineDoc, blocks: unknown, own: Owne
  * that step's undo still changes nothing.
  */
 export declare const deleteRange: (doc: EngineDoc, blocks: unknown, own: Ownership, b: BlockId, offset: number, length: number) => void;
+/**
+ * A suggestion's plan being written on a doc (`doc/suggest.ts`): its text
+ * deletes propose (fork patch YP32) into its record, `sort` telling each
+ * unit's lot (`1` its author's own: held; `2` proposed; `3` already
+ * proposed: stepped over).
+ */
+export declare const proposing: WeakMap<EngineDoc, {
+    into: EngineNode;
+    sort: (client: number, clock: number) => number;
+}>;
 export declare const formatRangeIn: (doc: EngineDoc, blocks: unknown, own: Ownership, b: BlockId, offset: number, length: number, formats: Record<string, unknown>) => void;
 /**
  * Delete the content of streams `streams` (the room's purge of a

package/dist/crdt/text/model.js

@@ -198,8 +198,15 @@ export const deleteRange = (doc, blocks, own, b, offset, length) => {
     const records = doc.get(TEXT_DELETES_ROOT);
     const fresh = openInserts(doc);
     for (const r of rangesOf(flatten(b, blocks, own), offset, offset + length))
-        r.text.delete(r.a, r.b - r.a, records, fresh);
+        r.text.delete(r.a, r.b - r.a, records, fresh, proposing.get(doc));
 };
+/**
+ * A suggestion's plan being written on a doc (`doc/suggest.ts`): its text
+ * deletes propose (fork patch YP32) into its record, `sort` telling each
+ * unit's lot (`1` its author's own: held; `2` proposed; `3` already
+ * proposed: stepped over).
+ */
+export const proposing = new WeakMap();
 export const formatRangeIn = (doc, blocks, own, b, offset, length, formats) => {
     for (const r of rangesOf(flatten(b, blocks, own), offset, offset + length))
         writeMarks(doc, r.text, r.a, r.b - r.a, formats);

package/dist/crdt/text/runs.d.ts

@@ -220,38 +220,42 @@ export type RunView = {
     debug: RunViewDebug;
 };
 /**
- * The role table — one answer per kind, which the display and the
- * document's guards both ask. `childless`: kinds that display no children
- * (void roles) — a child of such a block displays in its slot.
- * `island`: a block promoted out of an island kind displays as
- * `defaultChild` of its display parent's kind (`null`: the root). `line`:
- * an island declared `lines` holds only lines — each direct child displays
- * as its line kind and holds no children. `container`: a
- * kind that renders no content and is neither void nor an island (a list)
- * — a block promoted out of one follows like one promoted out of an island. `rendersContent`: no block that renders content ever shows
- * as a kind that does not (its text would vanish). `layout`: a
- * layout kind displays only its items, and only two or more (`layout.*`).
- * `table`: a table kind displays only its rows, a row only its cells, in
- * the table's column order (`table.*`).
+ * A kind's answers, read once from its role (the one shape the display and
+ * every guard read). `childless`: displays no children (a void role) — a
+ * child of such a block displays in its slot. `island`: a block promoted
+ * out of one displays as `child` of its display parent's kind.
+ * `container`: renders no content and is neither void nor an island (a
+ * list) — a block promoted out of one follows like one promoted out of an
+ * island. `rendersContent`: no block that renders content ever shows as a
+ * kind that does not (its text would vanish). `child`: its default child
+ * (the document's default kind for the root, `null`). `line`: an island
+ * declared `lines` holds only lines of this kind, which hold no children.
+ * `layout`: a layout displays only items of this kind, and only two or
+ * more (`layout.*`). `table`: a table displays only rows of this kind, a
+ * row only its cells, in the table's column order (`table.*`).
  */
+export type KindRole = {
+    childless: boolean;
+    island: boolean;
+    container: boolean;
+    rendersContent: boolean;
+    child: string;
+    line?: string;
+    layout?: string;
+    table?: string;
+};
+/** The kinds the roles declare: line kinds, layout kinds and their item kinds, table kinds and their row kinds (→ cell kind). */
+export type DeclaredKinds = {
+    lines: ReadonlySet<string>;
+    layouts: readonly string[];
+    items: ReadonlySet<string>;
+    rows: ReadonlyMap<string, string>;
+    cells: ReadonlySet<string>;
+};
+/** The role table: each kind's {@link KindRole} and the declared kinds, both read once until the roles change. */
 export type DisplayRoles = {
-    childless: (type: string) => boolean;
-    island: (type: string) => boolean;
-    container: (type: string) => boolean;
-    rendersContent: (type: string) => boolean;
-    defaultChild: (parentType: string | null) => string;
-    /** The line kind of an island kind declared `lines` (its `defaultChild`), if any. */
-    line: (islandType: string) => string | undefined;
-    /** Every line kind the roles declare, present in the document or not. */
-    lineKinds: () => Iterable<string>;
-    /** The item kind of a layout kind (its `defaultChild`), if `type` is one. */
-    layout: (type: string) => string | undefined;
-    /** Every layout kind the roles declare, present in the document or not. */
-    layoutKinds: () => Iterable<string>;
-    /** The row kind of a table kind (its `defaultChild`), if `type` is one (`table.*`). */
-    table: (type: string) => string | undefined;
-    /** Every table kind the roles declare, present in the document or not. */
-    tableKinds: () => Iterable<string>;
+    of: (type: string | null) => KindRole;
+    declared: () => DeclaredKinds;
 };
 /** The doc's index — built on first use, torn down when the doc is destroyed. */
 export declare const indexOf: (doc: EngineDoc) => RunView;

package/dist/crdt/vendor/yjs/UPSTREAM.md

@@ -1515,6 +1515,89 @@ Oracle: `src/tests/crdt/attribution/first-write-binding.test.ts` (the first
 local edit's one update carries the binding; a remote update writes none),
 the upstream suite.
 
+### YP31 — a hold record inside a nested node holds nothing (`src/structs/Item.js`)
+
+Reason: edytor's shared suggestions keep, inside each suggestion's record
+node, the id ranges it proposes to delete and the ranges its reviewers
+settled: lists of `client, clock, len` ranges that must hide nothing until a
+reviewer accepts. YP20's hold record is exactly that codec (one unit per
+range, a left id and a length, consecutive records of one writer merging
+as typed runs do), but it holds whatever it names wherever it integrates.
+The study's prototype added a sibling content type that held nothing
+(content ref 14, `ContentPropose`, a `YNode#propose` writer, about 0.3 KB);
+the rule here keeps one record type and one reader. Design:
+`docs/archive/shared-suggestions/design.md`. Edytor's schema generation 11
+is the cutover (no conversion: a generation-10 replica would hold what a
+proposal names).
+
+Patch (new code delimited by `// YP31 begin` / `// YP31 end`, edits marked `// YP31`):
+
+- **`holding(item)`**: a hold record holds what it names iff its item is an
+  entry of a root's sequence (`item.parent._item === null`: the document's
+  records list, `textdel`). `ContentHold#integrate` and `ContentHold#delete`
+  hold and release only then; inside a nested node's sequence the record is
+  a list of ids: it moves no length, waits in no `pendingHolds`, logs
+  nothing in `transaction.holds`, and its delete (an undo, a reviewer's
+  withdrawal, its node's delete) releases nothing. `YNode#hold(ids)` on a
+  nested node appends one such list entry.
+
+Plain deletes and the root records list (every upstream test, every YP20
+row) are untouched: no other code path writes a hold record into a nested
+node.
+
+Edytor side: a suggestion's record node (root `suggest`) keeps its writer's
+proposed deletions and its reviewers' settled ranges as such entries
+(`crdt/doc/suggest.ts`); accepting a deletion writes a real hold record in
+the root list.
+
+Oracle: `src/tests/crdt/yp31-id-lists.test.ts` (written, deleted, merged,
+split, synced, reloaded, received before the items it names, deleted with
+its node: nothing hidden or released; the root list still holds), the YP20
+rows and the shared-suggestion rows, the upstream suite unchanged
+(`encoding.tests.js` still pins 14 content refs).
+
+### YP32 — a delete that proposes (`src/ynode.js`, `src/structs/Item.js`, `src/index.js`)
+
+Reason: in suggesting mode a text delete writes nothing to the text: the
+units that are not the suggestion's author's own pending ones are named by
+an id list in the suggestion's record (YP31), and they stay shown. The
+plan that deleted them was prepared with them gone, so edytor carried a
+layer that re-read each later step's offsets over the units the plan had
+proposed, batched the steps around every proposal and mapped the caret
+back (`crdt/doc/suggest.ts` `apply`, about 1.4 KB minified). The fork's
+delete now proposes, and hides what it proposed until the plan ends: the
+plan's later steps read the offsets they were prepared with, and an
+insertion at a proposed deletion lands after it (at the end of the gap,
+as any insertion lands after deleted items). Design:
+`docs/archive/suggestions-in-engine/design.md`.
+
+Patch (new code delimited by `// YP32 begin` / `// YP32 end`, edits marked `// YP32`):
+
+- **`YNode#delete(index, length, into, fresh, propose)`**: with `propose`
+  (`{ into, sort }`), each live unit the delete reaches is sorted by
+  `sort(client, clock)`: `1` held by the record appended to `into` (the
+  author's own pending text, YP20's path), `2` proposed (one id list
+  appended to `propose.into`, the suggestion's record, which holds nothing
+  there, YP31), `3` stepped over (already proposed). `fresh` units are
+  removed as before. Proposed and stepped-over units are hidden
+  (`hideIds`: a hold without a record, kept in `transaction.hidden`) until
+  `unhide(transaction)`, which edytor calls when the plan is written.
+  `deleteText` splits a run where the sort changes.
+- **`hideIds`, `unhide`** (`Item.js`, `unhide` exported): YP20's
+  `holdIds` with no record, and its release.
+
+Plain deletes (every upstream test, every YP20 row) are untouched: without
+`propose` the sort is not read and every changed path reduces to YP20's.
+
+Edytor side: `crdt/text/model.ts` `deleteRange` passes the plan's
+`proposing` context; `crdt/doc/suggest.ts` writes a suggesting plan as one
+frame, its caret anchored before `unhide` and resolved after.
+
+Oracle: the shared-suggestion rows (`src/tests/crdt/suggest/`, the random
+schedules with the index's self-checks on), `suggesting-input.test.tsx`
+(typing over a selection, a paste, Backspace and Delete over struck text),
+the YP20 rows, the upstream suite unchanged.
+
 ## Generated declarations (`dts/`)
 
 `svelte-package` copies JS verbatim but emits no `.d.ts` for JS inputs, so

package/dist/crdt/vendor/yjs/dts/index.d.ts

@@ -17,4 +17,4 @@ export { idAtIndex, indexOfId } from "./utils/positions.js";
 export { findIndexSS, getItemCleanStart, getItemCleanEnd, isKeptReplaced } from "./utils/transaction-helpers.js";
 export { Transaction, transact } from "./utils/Transaction.js";
 export { redoItem, keepItem } from "./utils/redo.js";
-export { Item, followRedone, ContentBinary, ContentDeleted, ContentFormat, ContentAny, ContentString, ContentType, ContentMove } from "./structs/Item.js";
+export { Item, followRedone, ContentBinary, ContentDeleted, ContentFormat, ContentAny, ContentString, ContentType, ContentMove, unhide } from "./structs/Item.js";

package/dist/crdt/vendor/yjs/dts/structs/Item.d.ts

@@ -427,13 +427,14 @@ export class ContentHold {
     mergeWith(right: ContentHold): boolean;
     /**
      * @param {Transaction} transaction
-     * @param {Item} _item
+     * @param {Item} item
      */
-    integrate(transaction: Transaction, _item: Item): void;
+    integrate(transaction: Transaction, item: Item): void;
     /**
      * @param {Transaction} transaction
+     * @param {Item} item
      */
-    delete(transaction: Transaction): void;
+    delete(transaction: Transaction, item: Item): void;
     /**
      * @param {Transaction} _tr
      */
@@ -449,6 +450,8 @@ export class ContentHold {
      */
     getRef(): 11;
 }
+export function hideIds(tr: Transaction, ids: Array<number>): void;
+export function unhide(tr: Transaction): void;
 export function applyPending(tr: Transaction, clients: Array<number>): void;
 /**
  * A move record: one countable unit at its destination, naming the units

package/dist/crdt/vendor/yjs/dts/ynode.d.ts

@@ -25,7 +25,7 @@ export class ItemTextListPosition {
     advance(transaction: Transaction, length: number): void;
 }
 export function insertAtGapEndHelper(transaction: Transaction, parent: YNode, index: number, content: import("./structs/Item.js").AbstractContent): void;
-export function deleteText(transaction: Transaction, currPos: ItemTextListPosition, length: number, held?: Array<number> | null, fresh?: import("./utils/ids.js").IdSet | null): ItemTextListPosition;
+export function deleteText(transaction: Transaction, currPos: ItemTextListPosition, length: number, held?: Array<number> | null, fresh?: import("./utils/ids.js").IdSet | null, sort?: ((client: number, clock: number) => number) | null, proposed?: Array<number> | null, hidden?: Array<number> | null): ItemTextListPosition;
 export class ArraySearchMarker {
     /**
      * @param {Item} p
@@ -193,12 +193,23 @@ export class YNode {
      * which an undo of the record takes back), except those `fresh` names (the
      * open undo step's inserts: removed, so that step's undo changes nothing).
      *
+     * YP32: with `propose` (a suggestion's delete) each unit is sorted: held
+     * by the record in `into` (`1`: its author's own), proposed (`2`: an id
+     * list appended to `propose.into`, a suggestion's record, holding nothing)
+     * or stepped over (`3`: already proposed); proposed and stepped-over units
+     * read gone until `unhide`, so the rest of the plan reads the offsets it
+     * was prepared with.
+     *
      * @param {number} index Index at which to start deleting elements
      * @param {number} length The number of elements to remove. Defaults to 1.
      * @param {YNode|null} [into]
      * @param {import('./utils/ids.js').IdSet|null} [fresh]
+     * @param {{ into: YNode, sort: (client: number, clock: number) => number }|null} [propose]
      */
-    delete(index: number, length?: number, into?: YNode | null, fresh?: import("./utils/ids.js").IdSet | null): void;
+    delete(index: number, length?: number, into?: YNode | null, fresh?: import("./utils/ids.js").IdSet | null, propose?: {
+        into: YNode;
+        sort: (client: number, clock: number) => number;
+    } | null): void;
     /**
      * YP20: append to this node (the document's records list) one hold record of
      * the items `ids` names (`client, clock, len` triples): they read as deleted

package/dist/crdt/vendor/yjs/src/index.js

@@ -19,7 +19,7 @@ export { RangeCursor } from './utils/RangeCursor.js'
 export { YNode as Node } from './ynode.js'
 export { AbstractStruct } from './structs/AbstractStruct.js'
 export { GC } from './structs/GC.js'
-export { Item, followRedone, ContentBinary, ContentDeleted, ContentFormat, ContentAny, ContentString, ContentType, ContentMove } from './structs/Item.js' // YP22: ContentMove
+export { Item, followRedone, ContentBinary, ContentDeleted, ContentFormat, ContentAny, ContentString, ContentType, ContentMove, unhide } from './structs/Item.js' // YP22: ContentMove; YP32: unhide
 export { Skip } from './structs/Skip.js'
 
 /**

package/dist/crdt/vendor/yjs/src/structs/Item.js

@@ -1134,17 +1134,18 @@ export class ContentHold {
 
   /**
    * @param {Transaction} transaction
-   * @param {Item} _item
+   * @param {Item} item
    */
-  integrate (transaction, _item) {
-    holdIds(transaction, this.ids, 1)
+  integrate (transaction, item) {
+    if (holding(item)) holdIds(transaction, this.ids, 1) // YP31
   }
 
   /**
    * @param {Transaction} transaction
+   * @param {Item} item
    */
-  delete (transaction) {
-    holdIds(transaction, this.ids, -1)
+  delete (transaction, item) {
+    if (holding(item)) holdIds(transaction, this.ids, -1) // YP31
   }
 
   /**
@@ -1170,6 +1171,44 @@ export class ContentHold {
 }
 // YP20 end
 
+// YP31 begin (edytor fork: id lists — see UPSTREAM.md YP31)
+/**
+ * Whether the hold record `item` holds what it names: one in a root's
+ * sequence does (the document's records list, YP20); one in a nested node's
+ * sequence is a list of ids, the same codec, that holds nothing.
+ *
+ * @param {Item} item
+ * @return {boolean}
+ */
+const holding = item => /** @type {YNode} */ (item.parent)._item === null
+// YP31 end
+
+// YP32 begin (edytor fork: a delete that proposes — see UPSTREAM.md YP32)
+/**
+ * Hide the units `ids` names until `unhide` (a suggestion's proposed
+ * deletion, which the rest of its plan reads gone): a hold without a
+ * record, kept in `tr.hidden`.
+ *
+ * @param {Transaction} tr
+ * @param {Array<number>} ids
+ */
+export const hideIds = (tr, ids) => {
+  holdIds(tr, ids, 1)
+  ;/** @type {any} */ (tr).hidden = (/** @type {any} */ (tr).hidden ?? []).concat(ids)
+}
+
+/**
+ * Show again what `hideIds` hid in `tr`.
+ *
+ * @param {Transaction} tr
+ */
+export const unhide = tr => {
+  const hidden = /** @type {any} */ (tr).hidden
+  if (hidden) holdIds(tr, hidden, -1)
+  ;/** @type {any} */ (tr).hidden = null
+}
+// YP32 end
+
 // YP22 begin (edytor fork: move records — see UPSTREAM.md YP22)
 /**
  * Whether move record `a` beats `b`: the greater `(priority, client, clock)`

package/dist/crdt/vendor/yjs/src/ynode.js

@@ -12,6 +12,7 @@ import {
   ContentType,
   ContentHold, // YP20
   ContentMove, // YP22
+  hideIds, // YP32
   readFormatValue, // YP25
   YXmlFragmentRefID,
   YXmlElementRefID,
@@ -327,19 +328,24 @@ const holdHelper = (transaction, list, ids) => {
 
 /**
  * With `held`, the live units are not deleted: their ids go to `held`
- * (`client, clock, len`), except those `fresh` names (YP20).
+ * (`client, clock, len`), except those `fresh` names (YP20). YP32: with
+ * `sort` (a suggestion's delete), `sort`'s `1` goes to `held`, `2` to
+ * `proposed` and `hidden`, `3` to `hidden`.
  *
  * @param {Transaction} transaction
  * @param {ItemTextListPosition} currPos
  * @param {number} length
  * @param {Array<number>|null} [held]
  * @param {import('./utils/ids.js').IdSet|null} [fresh]
+ * @param {((client: number, clock: number) => number)|null} [sort] YP32: a suggestion's delete sorts each unit
+ * @param {Array<number>|null} [proposed] YP32: the units it proposes
+ * @param {Array<number>|null} [hidden] YP32: the units it hides until `unhide`
  * @return {ItemTextListPosition}
  *
  * @private
  * @function
  */
-export const deleteText = (transaction, currPos, length, held = null, fresh = null) => {
+export const deleteText = (transaction, currPos, length, held = null, fresh = null, sort = null, proposed = null, hidden = null) => {
   const startLength = length
   let kept = 0 // YP20
   while (length > 0 && currPos.right !== null) {
@@ -347,15 +353,19 @@ export const deleteText = (transaction, currPos, length, held = null, fresh = nu
     if (!item.deleted && item.countable) {
       const { client, clock } = item.id
       // YP20: a held run ends where the open step's inserts start or end
-      const n = fresh === null ? math.min(length, item.length) : runEnd(fresh, client, clock, clock + math.min(length, item.length)) - clock
+      let n = fresh === null ? math.min(length, item.length) : runEnd(fresh, client, clock, clock + math.min(length, item.length)) - clock
+      // YP32: a suggestion's delete sorts each unit — held (`1`), proposed (`2`) or stepped over (`3`)
+      const kind = held === null || (fresh !== null && fresh.has(client, clock)) ? 0 : sort === null ? 1 : sort(client, clock)
+      if (kind !== 0 && sort !== null) for (let k = 1; k < n; k++) if (sort(client, clock + k) !== kind) n = k
       if (n < item.length) {
         getItemCleanStart(transaction, createID(client, clock + n))
       }
       length -= item.length
-      if (held === null || (fresh !== null && fresh.has(client, clock))) {
+      if (kind === 0) {
         item.delete(transaction)
       } else {
-        held.push(client, clock, item.length)
+        if (kind === 2) /** @type {Array<number>} */ (proposed).push(client, clock, item.length)
+        ;/** @type {Array<number>} */ (kind === 1 ? held : hidden).push(client, clock, item.length)
         kept += item.length
       }
     }
@@ -993,12 +1003,20 @@ export class YNode {
    * which an undo of the record takes back), except those `fresh` names (the
    * open undo step's inserts: removed, so that step's undo changes nothing).
    *
+   * YP32: with `propose` (a suggestion's delete) each unit is sorted: held
+   * by the record in `into` (`1`: its author's own), proposed (`2`: an id
+   * list appended to `propose.into`, a suggestion's record, holding nothing)
+   * or stepped over (`3`: already proposed); proposed and stepped-over units
+   * read gone until `unhide`, so the rest of the plan reads the offsets it
+   * was prepared with.
+   *
    * @param {number} index Index at which to start deleting elements
    * @param {number} length The number of elements to remove. Defaults to 1.
    * @param {YNode|null} [into]
    * @param {import('./utils/ids.js').IdSet|null} [fresh]
+   * @param {{ into: YNode, sort: (client: number, clock: number) => number }|null} [propose]
    */
-  delete (index, length = 1, into = null, fresh = null) {
+  delete (index, length = 1, into = null, fresh = null, propose = null) {
     if (!(length > 0)) return
     if (this.doc == null) {
       const runs = prelimOf(this).runs
@@ -1015,13 +1033,17 @@ export class YNode {
     transact(this.doc, transaction => {
       const currPos = cursorAt(transaction, this, index)
       const held = into === null ? null : [] // YP20
-      deleteText(transaction, currPos, length, held, fresh)
+      const [proposed, hidden] = [[], []] // YP32
+      deleteText(transaction, currPos, length, held, fresh, propose && propose.sort, proposed, hidden)
       if (held !== null && held.length > 0) {
         // YP20: `deleteText` moved the markers as for a delete; the hold keeps them
         const ms = this._searchMarker === null ? null : this._searchMarker.slice()
         holdHelper(transaction, /** @type {YNode} */ (into), held)
         if (ms !== null && this._searchMarker !== null) this._searchMarker.splice(0, this._searchMarker.length, ...ms)
       }
+      // YP32: the proposal, then what it hides until `unhide`
+      if (proposed.length > 0) holdHelper(transaction, /** @type {any} */ (propose).into, proposed)
+      if (hidden.length > 0) hideIds(transaction, hidden)
       plantMarker(this, currPos)
     })
   }

package/dist/edytor.svelte.d.ts

@@ -11,7 +11,7 @@ import { Handles } from './session/handles.js';
 import { type Awareness, type DocChange, type DocumentActor, type EdytorDocument, type OrderPolicy, type YDoc } from './crdt/index.js';
 import { PresenceWriter, type PresenceOptions } from './collaboration/awarenessSelection.js';
 import { type BlockMoveRequest } from './session/moves.js';
-import { type DocumentWrites } from './crdt/operations.js';
+import type { DocumentWrites } from './crdt/operations.js';
 import type { Plugin, BlockDefinition, MarkDefinition, InlineBlockDefinition, EditorCommand, Placeholder } from './plugins.js';
 import { type HotKey, type HotKeyCombination } from './session/keymap.js';
 import { Dispatcher } from './session/commands.js';