edytor 1.0.0-rc.3 → 2.0.0

package/dist/crdt/document.d.ts

@@ -28,7 +28,7 @@
  * owns: `destroy()` releases the document-created services but never
  * `doc.destroy()`s the borrowed doc (borrowing grants no destruction
  * authority). The same rule applies to an injected
- * `awareness` (the `_ownsAwareness` convention already used by
+ * `awareness` (the `#ownsAwareness` convention already used by
  * `IndexeddbPersistence`).
  *
  * ── Readiness ──────────────────────────────────────────────────────────
@@ -98,8 +98,8 @@
  *
  * ── History ────────────────────────────────────────────────────────────
  *
- * One registry-scoped `Y.UndoManager` per document (the facade's
- * supported seam). Capture is gated by TWO live checks, both consulted
+ * One registry-scoped undo manager per document (`doc/history.ts`, the
+ * facade's supported seam). Capture is gated by TWO live checks, both consulted
  * on every committing transaction:
  *
  * - `trackedOrigins` — a LIVE per-document set checked by identity: the
@@ -136,15 +136,15 @@
  * History is lazy: it attaches at `sync()`, or on first `history` access
  * once the doc is initialized — it NEVER initializes content itself, so
  * bootstrap/hydration writes all predate capture and are naturally
- * excluded. Stacks are unbounded (the engine prunes nothing); prune
- * explicitly via {@link clearHistory} / `history.clear()`, and tune the
- * merge window via `history.captureTimeout`.
+ * excluded. The undo stack keeps `history.limit` steps; drop them all
+ * via {@link clearHistory} / `history.clear()`, and tune the merge window
+ * via `history.captureTimeout`.
  */
 import type { MarkEdge } from './text/marks.js';
-import type { EngineApi, YDoc, YUndoManager } from './engine-api.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 EdytorDocBinding } from './edytor-doc.js';
+import { 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';
@@ -220,19 +220,6 @@ export type DocumentOptions = {
         captureTimeout?: number;
         limit?: number;
     };
-    /**
-     * Opt-in per-block lineage ring — `depth > 0` captures a subtree
-     * snapshot just before an edit displaces a block's current
-     * `lastChangedBy` owner (handoffs, deletes, undo/redo touches),
-     * ring-trimmed to this many entries per block. `0`/absent disables
-     * the feature: no captures, byte-identical writes. Read via
-     * {@link DocumentAttribution.history}. Must be a finite non-negative
-     * integer — `NaN`/`Infinity`/fractional/negative values raise
-     * `RangeError` at creation (an unbounded ring is worse than no ring).
-     */
-    lineage?: {
-        depth?: number;
-    };
     /**
      * Decide an EMPTY document only from a provider that synced: the
      * room answered, or a local store hydrated. A provider's bound or
@@ -285,7 +272,7 @@ export declare class DocumentDestroyedError extends Error {
  *
  * `sync()` is the only transition out of `pending`, and it is the
  * document-side admission re-check: a doc that arrived in a problem
- * state (unversioned/unsupported/foreign/legacy — e.g. via raw
+ * state (unversioned/unsupported/foreign — e.g. via raw
  * `applyUpdate` bypass writes) refuses there with a typed error, stays
  * `pending`, and preserves the state — never silently becoming `local`.
  */
@@ -304,8 +291,8 @@ export type EdytorDocumentInit = {
     doc: YDoc;
     /** Whether `destroy()` may `doc.destroy()` — true only for document-allocated docs. */
     ownsDoc: boolean;
-    /** The bound facade binding this document composes (injected by `bindDocument`). */
-    binding: EdytorDocBinding;
+    /** The facade factory this document composes (injected by `bindDocument`). */
+    facade: (doc: EngineDoc, config: EdytorDocConfig) => DocFacade;
     /** The bound attribution service (injected by `bindDocument`). */
     attribution: AttributionBinding;
     /** The engine this document's doc belongs to (for `encode`). */
@@ -319,9 +306,6 @@ export type EdytorDocumentInit = {
         captureTimeout?: number;
         limit?: number;
     };
-    lineage?: {
-        depth?: number;
-    };
     requireHydration?: boolean;
 };
 /**
@@ -330,12 +314,13 @@ export type EdytorDocumentInit = {
  */
 /**
  * The document's operations and reads are its own members
- * (`document.insertBlock(…)`, `document.toJSON()`): see `DocumentOperations`.
+ * (`document.insertBlocks(…)`, `document.toJSON()`): see `DocumentOperations`.
  * `transact` is the document's (its local origin by default).
  */
 export interface EdytorDocument extends Omit<DocumentOperations, 'transact'> {
 }
 export declare class EdytorDocument {
+    #private;
     /** The underlying engine doc — raw reads/providers borrow it; they never own it. */
     readonly doc: YDoc;
     /** One shared awareness instance for every view/provider of this document. */
@@ -343,10 +328,9 @@ export declare class EdytorDocument {
     /** The local actor identity (anonymous opaque id when none was supplied). */
     readonly actor: DocumentActor;
     /**
-     * The attribution surface — compact per-block records, the
-     * replicated actor dictionary (`u/` profiles, `c/` replica bindings),
-     * and a `legacy()` read over any pre-existing `a/` per-edit records
-     * written by earlier builds. Ordinary edits perform no attribution
+     * The attribution surface — compact per-block records and the
+     * 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
      * `src/lib/crdt/attribution/attribution.ts` for the full contract.
@@ -354,7 +338,7 @@ export declare class EdytorDocument {
      * lifecycle contract as {@link history}.
      *
      * Reads are pull-model: record arrivals emit no attribution-specific
-     * change event — every fresh `block()`/`actors`/`legacy()` call reads
+     * change event — every fresh `block()`/`actors` call reads
      * current replicated state.
      */
     get attribution(): DocumentAttribution;
@@ -366,69 +350,17 @@ export declare class EdytorDocument {
      * distinction.)
      */
     readonly transaction: TRANSACTION;
-    /**
-     * The live `trackedOrigins` set handed to the undo manager — checked
-     * live by the engine on every transaction, so origins may be added any
-     * time before/after history attaches. Contents:
-     * - `this.transaction` — the document's own headless local-edit origin;
-     * - `null` — untyped LOCAL transactions (direct `document.facade.<op>`
-     *   calls outside `document.transact`, raw `doc.transact(fn)` writes).
-     *   `null` can no longer admit remote state: `captureTransaction`
-     *   rejects every non-local commit before origins are even consulted —
-     *   keeping it preserves the documented headless-edit contract while
-     *   remote exclusion is enforced by `transaction.local`, not by origin
-     *   hygiene;
-     * - each attached view's `TRANSACTION` instance (via {@link trackOrigin}).
-     *
-     * Origins are tracked by IDENTITY, not class: a view's edits are only
-     * undoable through the document(s) it registered on — every view bound
-     * to ONE document shares its history. Views release their origin via
-     * {@link untrackOrigin} at teardown: already-captured stack items stay
-     * (their commits remain undoable), only FUTURE commits from the dead
-     * origin stop capturing.
-     */
-    private readonly _trackedOrigins;
-    private readonly _engine;
-    private readonly _ownsDoc;
-    private readonly _ownsAwareness;
-    private _history;
-    private readonly _attributionCtl;
-    /**
-     * `true` when the attached manager was destroyed by something other
-     * than this document — its `destroy()` is a public engine surface, so
-     * an external caller can kill it while the document lives. The getter
-     * reattaches a fresh manager rather than handing back the corpse.
-     */
-    private _readiness;
     private _destroyed;
-    /**
-     * Attach references — every `createDocument`/`loadDocument`/
-     * `attachDocument` grants ONE; each {@link retain} grants one more.
-     * `destroy()` and a `retain()` release each consume exactly ONE
-     * reference; the document tears down only when the last release
-     * lands (deduplicated `attachDocument` shares this instance across
-     * callers/views).
-     */
-    private _refs;
-    /** The adopted capability tables: per kind, the first declaration. */
-    private readonly _capability;
-    private _defaultType;
-    private readonly _historyOptions;
-    private readonly _lineageDepth;
     /** {@link DocumentOptions.requireHydration}: an empty document waits for a provider's `synced`. */
     readonly requireHydration: boolean;
-    /** Attached providers keyed by transport target: one per target. */
-    private _providers;
-    private _pendingSyncs;
-    private _healOff;
-    private _readyListeners;
-    /**
-     * DEV: publish the digest of this document's roles in its presence
-     * (`semantics`, {@link semanticsDigest}), so a room reading other roles
-     * logs the kinds they differ on (`semanticsMismatch`). Re-published at
-     * each adoption; a production build advertises nothing.
-     */
-    private _advertise;
+    /**
+     * The document's properties as a live object (`crdt/props`): a read
+     * follows the document, and a write at any depth (`document.data.title
+     * = 'Notes'`, `document.data.tags.push('x')`, `delete …`) is the raw
+     * `patchData` operation at once, as `document.patchData(null, …)`. Not
+     * reactive by itself: a view's `edytor.data` is, and dispatches.
+     */
+    get data(): Record<string, any>;
     /** The replica id (`doc.clientID`) — identifies the replica, not the actor. */
     get clientID(): number;
     /**
@@ -496,20 +428,13 @@ export declare class EdytorDocument {
      * - `rendersContent` and `defaultChild` entries follow the same rule;
      * - `defaultType` must match the document's when supplied.
      *
-     * Atomic: everything validates before anything is adopted.
+     * Atomic: everything validates before anything is adopted (the merge is
+     * `mergeSemantics`'s).
      *
      * Contributions are document-lifetime: they survive the contributing
      * view's teardown, so sibling views keep the same structural rules.
      */
     adoptSemantics: (config: DocumentSemanticsConfig) => void;
-    /**
-     * DEV: `layout` needs a default child (its item kind); `lines` needs an
-     * island with a default child (its line kind), and
-     * the line kind belongs to it — outside such an island a block of that
-     * kind shows as its parent's default child, so a kind other blocks use
-     * (the default type, another kind's default child) would be recast.
-     */
-    private _warnLines;
     /**
      * The readiness transition — decide the document's content state. This
      * is the document-side admission re-check ({@link assertAdmission} —
@@ -521,7 +446,7 @@ export declare class EdytorDocument {
      * - `'initialized'` verdict (provider-hydrated, or a loaded restore) →
      *   the schema was just asserted; content is left alone;
      * - a doc in a problem state (unversioned/unsupported/foreign schema
-     *   claim, legacy layout — possible via raw `applyUpdate` writes that
+     *   claim — possible via raw `applyUpdate` writes that
      *   bypass the transport gate) REFUSES readiness: the typed error
      *   propagates, the document stays `pending`, and the doc's state is
      *   preserved. Retrying after the state heals (e.g. a remote update
@@ -536,7 +461,7 @@ export declare class EdytorDocument {
      */
     sync: (value?: JSONDoc) => void;
     /**
-     * The default local history (registry-scoped `Y.UndoManager` —
+     * The default local history (the registry-scoped undo manager —
      * `undo`/`redo`/`stopCapturing`/stacks). Lazy: attaches at `sync()`,
      * or on first access once the document is decided — it NEVER seeds
      * content itself (accessing it on a pending doc throws
@@ -563,7 +488,6 @@ export declare class EdytorDocument {
      * throw — a dead document has already dropped its manager anyway).
      */
     untrackOrigin: (origin: unknown) => void;
-    private _attachHistory;
     /**
      * Drop the undo/redo stacks. The undo stack already keeps only its
      * newest `history.limit` steps; call this where undo no longer makes
@@ -593,9 +517,6 @@ export declare class EdytorDocument {
      * bound. An editable view decides a pending document only when none is.
      */
     get syncPending(): boolean;
-    /** The standing refusal of each attached target that reported one, oldest first. */
-    private _refusals;
-    private _refusalListeners;
     /**
      * The server's refusal of a provider (a `1008`/`4xxx` close — see
      * `SyncRefusedError`), the latest still standing: that provider
@@ -680,8 +601,6 @@ export declare class EdytorDocument {
      * grants no destruction authority). Post-teardown calls are a no-op.
      */
     destroy: () => void;
-    /** Shared reference release — `destroy()` and `retain()` closures land here. */
-    private _releaseReference;
 }
 export type DocumentBinding = ReturnType<typeof bindDocument>;
 /**
@@ -706,9 +625,8 @@ export declare const bindDocument: (Y: EngineApi) => {
      * state). Staged admission: the payload is
      * decoded+integrated onto a SCRATCH doc and the document admission
      * gate runs on the merged result — a corrupt payload
-     * ({@link UndecodableUpdateError}), a v13-era layout
-     * ({@link UnsupportedDocError} `'legacy'` → migration path), or a
-     * schema claim this build cannot own ({@link SchemaMismatchError})
+     * ({@link UndecodableUpdateError}, a v13 document's bytes among
+     * them), or a schema claim this build cannot own ({@link SchemaMismatchError})
      * refuses BEFORE the facade/history/awareness ever compose, and
      * the caller's bytes are never touched. Only then does `sync()`
      * complete readiness (history attaches after the restored schema
@@ -724,8 +642,7 @@ export declare const bindDocument: (Y: EngineApi) => {
      * provider path) drives `sync()`.
      *
      * Admission runs BEFORE any composition touches the doc: a
-     * foreign engine object or applied-but-unmigrated v13 state
-     * refuses with {@link UnsupportedDocError}, an
+     * foreign engine object refuses with {@link UnsupportedDocError}, an
      * unversioned/unsupported/foreign schema claim with
      * {@link SchemaMismatchError} — the borrowed doc is left
      * byte-identical (the gate reads are write-free) and can be