edytor 1.0.0-rc.2 → 1.0.0

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

@@ -46,14 +46,15 @@
  * blocks it claims. A split inserts one boundary; a merge appends one claim;
  * no text is ever copied.
  *
- * The module is engine-agnostic: `bindModel(Y)` takes the vendored module
- * surface so this file type-checks against structural interfaces and never
- * imports vendor `.js` (which `pnpm check` must not traverse).
+ * The engine is the vendored one, read through `engine.js` (structural
+ * types, `engine-api.ts`): this file never imports vendor `.js` (which
+ * `pnpm check` must not traverse).
  *
  * Placement resolution is `placement/resolve.ts`, the source ranks
  * `placement/source.ts`, where a block displays `placement/display.ts`
- * (re-exported here); this module declares the model's types and binds the
- * write and read primitives to an engine.
+ * (re-exported here); this module declares the model's types and its write
+ * and read primitives, each a function edytor's modules import (the
+ * public binding's `model` lists them, `bindModel`).
  */
 import type { EngineApi, EngineDoc, EngineItemRef, EngineNode } from '../engine-api.js';
 import { REGISTRY_KEY } from '../schema.js';
@@ -110,7 +111,7 @@ export type ProjectedDoc = {
 export { REGISTRY_KEY };
 export { candidatesOf, resolvePlacements } from './resolve.js';
 export { promotedRank, sourceRank, SOURCE_SIDE } from './source.js';
-export { bySlot, childrenIndex, displayIndex, displayParentOf, displaySlotOf, documentOrder, isLiveIn, textRanker } from './display.js';
+export { bySlot, childrenIndex, displayParentOf, displaySlotOf, documentOrder, isLiveIn, textRanker } from './display.js';
 /** Placement value written atomically as one attr: `{p, r}`. */
 export type PlacementValue = {
     p: BlockId | null;
@@ -239,14 +240,161 @@ export type DocOrder = {
     ids: readonly BlockId[];
     at: ReadonlyMap<BlockId, number>;
 };
+export declare const registryOf: (doc: EngineDoc) => EngineNode;
+export declare const blockNodeOf: (doc: EngineDoc, id: BlockId) => EngineNode | null;
 /**
- * Bind the placement model to a concrete engine surface.
+ * The registry node when it carries no delete mark — the DELETED half of
+ * deleted-vs-hidden (a block under a deleted parent is hidden, not
+ * deleted). Not a targetability answer: ops ask {@link isLive}.
+ */
+export declare const liveNodeOf: (doc: EngineDoc, id: BlockId) => EngineNode | null;
+/** {@link isLiveIn} over the doc's current view. */
+export declare const isLive: (doc: EngineDoc, id: BlockId) => boolean;
+/**
+ * The history's creation rule (`doc/history.ts`, `hist.undo.withdraw`): an
+ * undo never deletes a block the undone step created. Its node and
+ * structure (attrs, placement candidates, the content and claims nodes)
+ * stay and the undoer's withdraw mark is written on it; what the step wrote
+ * inside the content and claims nodes (the undoer's own text, atoms,
+ * boundaries, claims) is deleted as usual. The index shows a withdrawn
+ * block while it holds another writer's content.
+ */
+export declare const withdrawOnUndo: (doc: EngineDoc) => (item: EngineItemRef, stackItem: {
+    inserts: {
+        has(client: number, clock: number): boolean;
+    };
+}) => boolean;
+/**
+ * Atomically append one placement candidate `{p, r}` to a block's `at`
+ * map, stamped `seq = localMax+1, client = doc.clientID`, then compact:
+ * candidates below the top-2 are tombstoned (the runner-up survives as
+ * the acyclic fallback; deeper history is re-created by undo anyway).
+ * Must run inside a transaction.
+ */
+export declare const writePlacement: (doc: EngineDoc, node: EngineNode, p: BlockId | null, r: string) => void;
+/** The doc's index as a `ModelView` — folded up to the open transaction's last write. */
+export declare const view: (doc: EngineDoc) => ModelView;
+/** A detached inline-atom node (inputs arrive normalized by the facade's ingress). */
+export declare const buildInline: (atom: InlineSpec) => EngineNode;
+/**
+ * True iff `maybeAncestor` is `id` itself or lies on `id`'s
+ * DISPLAY-ancestor chain — the composed relation `owner(parent)`
+ * (`displayParentOf`), not the raw placement chain. A merge claim can
+ * place a block inside another's display subtree without appearing in
+ * its raw ancestry, so the merge refusal must see through the claim
+ * redirect — this is exactly the relation `resolvePlacements` keeps
+ * acyclic: a merge that would close a cycle is refused without mutation.
+ */
+export declare const isSelfOrDescendant: (placements: Map<BlockId, ResolvedPlacement>, own: Ownership, id: BlockId, maybeAncestor: BlockId) => boolean;
+/**
+ * `count` consecutive insertion ranks at `index` into the sibling list
+ * `siblings`.
  *
- * `Y` must be the vendored v14 module (`import * as Y from
- * 'lib/crdt/vendor/yjs'`). Consumers inject it so this file stays free of
- * runtime vendor imports (see `engine-api.ts`).
+ * Degenerate seams (`left >= right`) are legal replicated states, not
+ * caller errors: equal-rank neighbours occur after cycle-fallback
+ * rehoming (two blocks may carry the same rank string minted in
+ * different sibling lists), and `rankBetween` THROWS on them — so
+ * callers must guard. No string sorts strictly between equal strings,
+ * so each new member takes `left` verbatim: it JOINS the tie and the
+ * `(rank, id)` display sort orders the whole group deterministically.
+ * On a valid seam the emitted chain is `rankBetween(left, right)` then
+ * `rankBetween(prev, right)` — with `run`, `rankAfter` (an insert: after a
+ * block this client ranked, in its run there).
+ */
+export declare const ranksAt: (siblings: readonly {
+    rank: string;
+}[], index: number, count: number, clientId: number, rand?: () => number, run?: boolean) => string[];
+/**
+ * Restore definition (migration only; a first import
+ * restores into an empty doc): make `specs` the whole visible document
+ * under their own ids, in ONE transaction. An existing id keeps its
+ * registry entry: every delete mark is cleared and its type, data,
+ * placement and content are rewritten in place — a fresh own text holding
+ * the spec's content and an empty claims list; a block whose stream still
+ * starts at a live boundary gets a new nonce, so that boundary goes inert
+ * and the own text is its stream. An absent id is created. Every other
+ * block gets this writer's delete mark. Ranks are derived from the tree
+ * alone and the rewrites are last-writer-wins attrs, so two replicas
+ * restoring the same specs converge on one copy.
+ */
+export declare const restoreBlocks: (doc: EngineDoc, specs: BlockSpec[]) => void;
+/**
+ * Materialize one spec subtree: the block owns its backing text (its
+ * stream from index 0); children recurse under a fresh sequential rank
+ * chain (a new block has no siblings to interleave with).
+ */
+export declare const materializeSpec: (doc: EngineDoc, sp: BlockSpec, parent: BlockId | null, rank: string) => void;
+/**
+ * Does any id of `specs` (whole subtrees) collide — with another spec id,
+ * or with any registry entry, live or deleted? The registry is keyed by
+ * id, so writing a taken id would replace that block in place.
+ */
+export declare const collides: (doc: EngineDoc, specs: readonly BlockSpec[]) => boolean;
+/**
+ * The seed writer's bulk insert (the document is written by document
+ * operations and, once, by the seed writer — `init`, the local
+ * materializer): `specs` (whole subtrees, in list order) at `dest` in one
+ * transaction, all-or-nothing — `false` without writing when the parent
+ * is not live or any id collides. Document operations never call it:
+ * they prepare their inserts (`insertBlocks` in the facade).
+ */
+export declare const insertBlocks: (doc: EngineDoc, dest: Destination, specs: BlockSpec[]) => boolean;
+/** {@link insertBlocks} of one spec. */
+export declare const insertBlock: (doc: EngineDoc, dest: Destination, spec: BlockSpec) => boolean;
+/**
+ * Split `id` at content `offset` into the new block `newId` placed at
+ * `place`: one boundary item for `newId` at the end of the gap at `offset`
+ * (fork patch YP7) and the merge claims that follow it re-inserted on the new block —
+ * no text is copied, so an offline edit to the tail keeps landing on the
+ * same items and displays in the new block after convergence. `tail` is
+ * the new block's type/data, decided once by the plan. Children are a
+ * separate step. `id` must have a stream or a claim ({@link ownText}).
+ */
+export declare const writeSplit: (doc: EngineDoc, id: BlockId, offset: number, newId: BlockId, tail: SplitTail, place: PlacementValue) => void;
+/**
+ * Give the streamless block `id` its own text (`T.ownText`: a derived
+ * writer, a re-minted nonce) — before the first write that needs a stream.
+ */
+export declare const ownText: (doc: EngineDoc, id: BlockId) => {
+    from: unknown;
+    to: number;
+};
+/**
+ * Canonical projection: pure derivation from replicated state — the
+ * visible tree of live blocks ordered by `(rank, id)`, children of a
+ * merged-away parent under its owner, those of a deleted parent in its
+ * slot ({@link displaySlotOf}). Content is each block's display.
+ */
+export declare const project: (doc: EngineDoc) => ProjectedDoc;
+/**
+ * `positionOf` in a view: the display parent and the index among its
+ * visible children — a binary search by the block's display rank (the
+ * list's own order), not a scan of its siblings.
+ */
+export declare const positionInView: (v: ModelView, id: BlockId) => Destination | null;
+/**
+ * `{parent, index}` of `id` in the visible tree, or null when hidden/absent.
+ * `parent` is the DISPLAY parent (merged-away ancestors resolve to their
+ * owner — see `displayParentOf`).
+ */
+export declare const positionOf: (doc: EngineDoc, id: BlockId) => Destination | null;
+/** Pre-order ids of the visible tree — the document order. */
+export declare const listBlockIds: (doc: EngineDoc) => BlockId[];
+/** Flat text of a block's OWNED content (atoms render as ''). */
+export declare const blockText: (doc: EngineDoc, id: BlockId) => string | null;
+/**
+ * Engine identity of the registry entry (`client:clock` of its item), or
+ * null when the block is absent from the visible tree (deleted, or hidden
+ * under a deleted/unreachable ancestor).
+ */
+export declare const crdtId: (doc: EngineDoc, id: BlockId) => string | null;
+/** Engine handle for a logical id, or null when absent or delete-marked (debug surface). */
+export declare const resolveBlock: (doc: EngineDoc, id: BlockId) => EngineNode | null;
+/**
+ * The placement model as one object (the public binding's `model`): the
+ * primitives above. Edytor's own modules import them directly.
  */
-export declare const bindModel: (Y: EngineApi) => {
+export declare const bindModel: (_Y: EngineApi) => {
     REGISTRY_KEY: string;
     registryOf: (doc: EngineDoc) => EngineNode;
     blockNodeOf: (doc: EngineDoc, id: BlockId) => EngineNode | null;
@@ -266,7 +414,7 @@ export declare const bindModel: (Y: EngineApi) => {
     writePlacement: (doc: EngineDoc, node: EngineNode, p: BlockId | null, r: string) => void;
     withdrawOnUndo: (doc: EngineDoc) => (item: EngineItemRef, stackItem: {
         inserts: {
-            hasId(id: unknown): boolean;
+            has(client: number, clock: number): boolean;
         };
     }) => boolean;
     materializeSpec: (doc: EngineDoc, sp: BlockSpec, parent: BlockId | null, rank: string) => void;