edytor 2.0.0 → 4.0.0

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, rendersContentOf, view, blockTypeOf, childrenIds, positionOf, ancestorsOf, is, 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
@@ -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/types.d.ts

@@ -8,7 +8,7 @@ import type { AttributionActor } from '../attribution/index.js';
 import type { BlockId, BlockSpec, InlineSpec, ProjectedBlock, SplitTail } from '../placement/model.js';
 import type { Anchor } from '../text/model.js';
 import type { ContentRun } from '../text/runs.js';
-import type { DataPatch, LeafWrite } from '../data.js';
+import type { DataPatch, DataWrite } from '../data.js';
 import type { DocPosition } from '../rangeDelete.js';
 /** Structural role of a block type (plugin-side policy, resolved per op). */
 export type BlockRole = {
@@ -180,22 +180,34 @@ export type TextRange = {
 /**
  * One planned write, named by the document operation that
  * performs it — the name a hook matches. Steps carry everything
- * their write needs (ranks, marks, offsets), decided at prepare time.
+ * their write needs (places, marks, offsets), decided at prepare time; a
+ * place is a display index among a parent's children, read against the
+ * document as the step is written (the steps before it applied).
  */
 export type PlanStep = 
-/** `index`: the destination slot at prepare time, as hooks see it. */
+/** `index`: the destination slot, as hooks see it. */
+/** `split`: the split-born block of this plan whose boundary these blocks' slots take as their sort key (a paste's lines at its split). */
 {
     op: 'insertBlocks';
     parent: BlockId | null;
     index: number;
     specs: BlockSpec[];
-    ranks: string[];
-} | {
+    split?: BlockId;
+}
+/**
+ * `side`: the move record's class among the items of its origin —
+ * absent or `0`, the blocks stand after what precedes them; `1`, before
+ * what follows them (blocks leaving a block for the gap before it).
+ */
+/** `side`: the record's class at its origin (`1`: before); `at`, `part`: the block it stands at and its order there (`moveTo`). */
+ | {
     op: 'moveBlocks';
     ids: BlockId[];
     parent: BlockId | null;
     index: number;
-    ranks: string[];
+    side?: 0 | 1;
+    part?: number;
+    at?: BlockId;
 }
 /** `marks`: the blocks that get this writer's mark; `removes`: those that leave the document. */
  | {
@@ -212,7 +224,7 @@ export type PlanStep =
     newId: BlockId;
     tail: SplitTail;
     parent: BlockId | null;
-    rank: string;
+    index: number;
 }
 /** `at`/`length`: where `from`'s display lands in `into`'s. */
  | {
@@ -229,7 +241,7 @@ export type PlanStep =
 /**
  * A data patch (`crdt/data.ts`): of block `id`, of its atom `inlineId`
  * (at display `offset`), or of the document (no `id`). `ops` as asked;
- * `leaves` the attr writes they plan.
+ * `writes` the attr and slot writes they plan.
  */
  | {
     op: 'patchData';
@@ -237,7 +249,7 @@ export type PlanStep =
     inlineId?: string;
     offset?: number;
     ops: DataPatch[];
-    leaves: LeafWrite[];
+    writes: DataWrite[];
 } | {
     op: 'insertText';
     id: BlockId;

package/dist/crdt/document.d.ts

@@ -50,10 +50,9 @@
  * bootstrap-shaped is written or broadcast, so writes made raw against a
  * pending doc produce unversioned state that `sync()` then refuses (see
  * below). `local`/`hydrated` — the full surface is legal; the only
- * difference is WHO decided the content. (One exception to "nothing
- * broadcast": the actor dictionary attach publishes this replica's
- * `c/<clientID>`/`u/<actorId>` records on ANY constructed document —
- * identity metadata, not content, and outside every admission gate.)
+ * difference is WHO decided the content. (The actor dictionary's
+ * `c/<clientID>`/`u/<actorId>` records go with the replica's first write,
+ * whatever it is: a document that is only read publishes nothing.)
  *
  * ── Admission boundary ────────────────────────────────────────────
  *
@@ -64,7 +63,7 @@
  * - `createDocument` — the fresh doc is trivially admitted;
  * - `loadDocument` — the payload is decoded+integrated onto a SCRATCH
  *   doc first (`admitUpdate`) and the gate runs on the merged result; a
- *   refusal ({@link UndecodableUpdateError}, {@link UnsupportedDocError},
+ *   refusal ({@link UndecodableUpdateError},
  *   {@link SchemaMismatchError}) leaves nothing composed and never
  *   touches the caller's bytes;
  * - `attachDocument` — the borrowed doc is gated BEFORE any composition
@@ -144,7 +143,7 @@ import type { MarkEdge } from './text/marks.js';
 import type { EngineApi, EngineDoc, YDoc, YUndoManager } from './engine-api.js';
 import { type DocumentOperations } from './operations.js';
 import { type AttributionBinding, type DocumentAttribution } from './attribution/index.js';
-import { type BlockRole, type DocFacade, type EdytorDocConfig } from './edytor-doc.js';
+import { DocumentDestroyedError, type BlockRole, type DocFacade, type EdytorDocConfig } from './edytor-doc.js';
 import { Awareness } from './protocols/awareness.js';
 import type { EdytorSync, EdytorSyncCleanup } from './providers/index.js';
 import { SyncRefusedError } from './providers/room.js';
@@ -243,19 +242,11 @@ export type CreateDocumentOptions = DocumentOptions & {
     value?: JSONDoc;
 };
 export type LoadDocumentOptions = DocumentOptions;
+export { DocumentDestroyedError };
 /** Raised when a readiness-gated service is used on a pending document. */
 export declare class DocumentNotReadyError extends Error {
     constructor(service: string);
 }
-/**
- * Raised when an operation runs against a torn-down document — every
- * attach reference has been released and the facade/history/awareness
- * teardown already ran. Distinct from {@link DocumentNotReadyError}:
- * destroyed is terminal, pending may still resolve.
- */
-export declare class DocumentDestroyedError extends Error {
-    constructor(service?: string);
-}
 /**
  * How the document's content state was decided — the distinction the
  * readiness contract requires:
@@ -332,7 +323,7 @@ export declare class EdytorDocument {
      * replicated actor dictionary (`u/` profiles, `c/` replica bindings).
      * Ordinary edits perform no attribution
      * writes — authorship lands inside the owning op's transaction as the
-     * block-level `b/<id>` record/`l` stamp. See
+     * block-level record (`blockattr` `<id>`)/`l` stamp. See
      * `src/lib/crdt/attribution/attribution.ts` for the full contract.
      * Access after teardown throws {@link DocumentDestroyedError} — same
      * lifecycle contract as {@link history}.
@@ -496,6 +487,18 @@ export declare class EdytorDocument {
      * on pending).
      */
     clearHistory: () => void;
+    /**
+     * End this session's history: the page it was edited in left for good.
+     * Every step is dropped, and what this replica deleted is released: the
+     * text its deletes hid is deleted for good now, and the room's purge
+     * removes the blocks it deleted at its next run, without waiting for the
+     * purge horizon (one small write, sent if the connection still can). A
+     * view calls it at a `pagehide` the back/forward cache keeps nothing of;
+     * a page kept there, or one that lost its connection, keeps its history.
+     * Undo starts empty afterwards. No-op while history has not attached, and
+     * on a destroyed document.
+     */
+    endHistory: () => void;
     /**
      * Local document transaction — headless edits, one undo step per call
      * (`origin`: another origin, which the document's history tracks only
@@ -641,9 +644,8 @@ export declare const bindDocument: (Y: EngineApi) => {
      * borrowed doc. Content state stays `pending` — the caller (view or
      * provider path) drives `sync()`.
      *
-     * Admission runs BEFORE any composition touches the doc: a
-     * foreign engine object refuses with {@link UnsupportedDocError}, an
-     * unversioned/unsupported/foreign schema claim with
+     * Admission runs BEFORE any composition touches the doc: an
+     * unversioned/unsupported/foreign schema claim refuses with
      * {@link SchemaMismatchError} — the borrowed doc is left
      * byte-identical (the gate reads are write-free) and can be
      * attached once its state heals (e.g. a remote update supplies the

package/dist/crdt/document.js

@@ -5,7 +5,7 @@ import { DOCUMENT_OPERATIONS } from './operations.js';
 import { propsProxy } from './props.js';
 import { bindAttribution } from './attribution/index.js';
 import { profileOf } from './attribution/attribution.js';
-import { docFacade, DEFAULT_HISTORY_LIMIT, isInitialized } from './edytor-doc.js';
+import { docFacade, DocumentDestroyedError, DEFAULT_HISTORY_LIMIT, isInitialized } from './edytor-doc.js';
 import { assertAdmission, assertSchema, bindAdmission, checkSchema } from './admission.js';
 import { Awareness } from './protocols/awareness.js';
 import { callEach } from './protocols/observable.js';
@@ -18,27 +18,14 @@ const alive = (document, op) => {
     if (document.destroyed)
         throw new DocumentDestroyedError(op);
 };
+export { DocumentDestroyedError };
 /** Raised when a readiness-gated service is used on a pending document. */
 export class DocumentNotReadyError extends Error {
     constructor(service) {
-        super(`EdytorDocument.${service}: document is not ready — it is still pending ` +
-            `(created without a value, provider hydration may be in flight). ` +
-            `Wait for the sync callback / call document.sync() first.`);
+        super(`${service}: the document is not ready (call document.sync() first)`);
         this.name = 'DocumentNotReadyError';
     }
 }
-/**
- * Raised when an operation runs against a torn-down document — every
- * attach reference has been released and the facade/history/awareness
- * teardown already ran. Distinct from {@link DocumentNotReadyError}:
- * destroyed is terminal, pending may still resolve.
- */
-export class DocumentDestroyedError extends Error {
-    constructor(service) {
-        super(`EdytorDocument${service ? `.${service}` : ''}: document is destroyed.`);
-        this.name = 'DocumentDestroyedError';
-    }
-}
 /**
  * How long (ms) an empty document waits for a provider that has not
  * settled before it decides without it (settle-or-bound) — the bound a
@@ -105,7 +92,7 @@ export class EdytorDocument {
      * replicated actor dictionary (`u/` profiles, `c/` replica bindings).
      * Ordinary edits perform no attribution
      * writes — authorship lands inside the owning op's transaction as the
-     * block-level `b/<id>` record/`l` stamp. See
+     * block-level record (`blockattr` `<id>`)/`l` stamp. See
      * `src/lib/crdt/attribution/attribution.ts` for the full contract.
      * Access after teardown throws {@link DocumentDestroyedError} — same
      * lifecycle contract as {@link history}.
@@ -226,9 +213,10 @@ export class EdytorDocument {
             this.awareness.setLocalStateField('user', user);
         // Attribution service — attaches after the facade (which gates
         // foreign docs) and after the actor is fixed. Publishes this
-        // replica's actor dictionary entries (`c/`+`u/`) once; ordinary
-        // edits perform no attribution work and per-block records are
-        // written inside the owning op's transaction by the facade.
+        // replica's actor dictionary entries (`c/`+`u/`) inside its first
+        // write's transaction; ordinary edits perform no attribution work
+        // and per-block records are written inside the owning op's
+        // transaction by the facade.
         this.#attributionCtl = init.attribution.attach(asEngineDoc(this.doc), {
             actor: this.actor
         });
@@ -514,6 +502,22 @@ export class EdytorDocument {
         alive(this, 'clearHistory');
         this.#_history?.clear();
     };
+    /**
+     * End this session's history: the page it was edited in left for good.
+     * Every step is dropped, and what this replica deleted is released: the
+     * text its deletes hid is deleted for good now, and the room's purge
+     * removes the blocks it deleted at its next run, without waiting for the
+     * purge horizon (one small write, sent if the connection still can). A
+     * view calls it at a `pagehide` the back/forward cache keeps nothing of;
+     * a page kept there, or one that lost its connection, keeps its history.
+     * Undo starts empty afterwards. No-op while history has not attached, and
+     * on a destroyed document.
+     */
+    endHistory = () => {
+        if (this._destroyed)
+            return;
+        this.#_history?.end();
+    };
     /**
      * Local document transaction — headless edits, one undo step per call
      * (`origin`: another origin, which the document's history tracks only
@@ -926,9 +930,8 @@ export const bindDocument = (Y) => {
          * borrowed doc. Content state stays `pending` — the caller (view or
          * provider path) drives `sync()`.
          *
-         * Admission runs BEFORE any composition touches the doc: a
-         * foreign engine object refuses with {@link UnsupportedDocError}, an
-         * unversioned/unsupported/foreign schema claim with
+         * Admission runs BEFORE any composition touches the doc: an
+         * unversioned/unsupported/foreign schema claim refuses with
          * {@link SchemaMismatchError} — the borrowed doc is left
          * byte-identical (the gate reads are write-free) and can be
          * attached once its state heals (e.g. a remote update supplies the