edytor 3.0.0 → 5.0.0

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 ────────────────────────────────────────────
  *
@@ -142,7 +141,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 { DocumentOperations } from './operations.js';
 import { type AttributionBinding, type DocumentAttribution } from './attribution/index.js';
 import { DocumentDestroyedError, type BlockRole, type DocFacade, type EdytorDocConfig } from './edytor-doc.js';
 import { Awareness } from './protocols/awareness.js';
@@ -278,6 +277,8 @@ export type DocumentReadiness = 'pending' | 'local' | 'hydrated';
  * does: from the socket's open, so a slow dial never counts).
  */
 export declare const DEFAULT_READINESS_BOUND = 1000;
+/** What a document's user may do in its room (`EdytorDocument.access`). */
+export type DocumentAccess = 'write' | 'suggest' | 'comment' | 'read';
 /** Internal constructor bag — use {@link createDocument}/{@link loadDocument}/{@link attachDocument}. */
 export type EdytorDocumentInit = {
     doc: YDoc;
@@ -324,7 +325,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}.
@@ -369,6 +370,13 @@ export declare class EdytorDocument {
      */
     get readiness(): DocumentReadiness;
     get destroyed(): boolean;
+    /**
+     * What this document's user may do, as its room said as it joined
+     * (`'write'` until a room says otherwise): `'suggest'` writes only
+     * suggestions, `'comment'` only comments, `'read'` nothing. The plugins
+     * read it (the shared suggestions' suggesting mode, the comments).
+     */
+    access: DocumentAccess;
     /**
      * `false` while the document carries a schema stamp this build cannot
      * own (a foreign stamp got in despite the transport's inbound refusal):
@@ -488,6 +496,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

package/dist/crdt/document.js

@@ -1,7 +1,6 @@
 import { DEV } from 'esm-env';
 import { Y } from './engine.js';
 import { asEngineDoc } from './structs.js';
-import { DOCUMENT_OPERATIONS } from './operations.js';
 import { propsProxy } from './props.js';
 import { bindAttribution } from './attribution/index.js';
 import { profileOf } from './attribution/attribution.js';
@@ -92,7 +91,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}.
@@ -192,13 +191,15 @@ export class EdytorDocument {
             // with the `SchemaMismatchError` naming the stamp.
             assertWritable: () => assertSchema(asEngineDoc(this.doc), 'document')
         });
-        // The document's own operations (`DocumentOperations`): the bound
-        // facade's, read through so each call reaches the live binding.
-        for (const name of DOCUMENT_OPERATIONS) {
-            if (name === 'transact')
-                continue;
-            Object.defineProperty(this, name, { get: () => this.facade[name], configurable: true });
-        }
+        // The document's own operations (the facade's `api`, which satisfies
+        // `DocumentOperations`): the bound facade's, read through so each
+        // call reaches the live binding.
+        for (const name in this.facade.api)
+            if (name !== 'transact')
+                Object.defineProperty(this, name, {
+                    get: () => this.facade[name],
+                    configurable: true
+                });
         this.awareness = init.awareness ?? new init.awarenessCtor(this.doc);
         this.#ownsAwareness = init.awareness === undefined;
         this.#historyOptions = init.history;
@@ -213,9 +214,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
         });
@@ -260,6 +262,13 @@ export class EdytorDocument {
     get destroyed() {
         return this._destroyed;
     }
+    /**
+     * What this document's user may do, as its room said as it joined
+     * (`'write'` until a room says otherwise): `'suggest'` writes only
+     * suggestions, `'comment'` only comments, `'read'` nothing. The plugins
+     * read it (the shared suggestions' suggesting mode, the comments).
+     */
+    access = 'write';
     /**
      * `false` while the document carries a schema stamp this build cannot
      * own (a foreign stamp got in despite the transport's inbound refusal):
@@ -359,8 +368,7 @@ export class EdytorDocument {
         // promoted out of a newly island kind displays as a default child; a
         // newly layout kind displays only its items (`layout.*`), a newly
         // table kind only its rows (`table.*`).
-        if (Object.values(config.roles ?? {}).some((role) => role?.void || role?.island || role?.layout || role?.table))
-            this.facade.rolesChanged();
+        this.facade.rolesChanged(Object.values(config.roles ?? {}).some((role) => role?.void || role?.island || role?.layout || role?.table));
     };
     /**
      * The readiness transition — decide the document's content state. This
@@ -501,6 +509,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
@@ -663,7 +687,8 @@ export class EdytorDocument {
                     bound = setTimeout(decide, DEFAULT_READINESS_BOUND);
                 },
                 holdBound: () => clearTimeout(bound),
-                attach: (companion) => this.attachSync(companion, opts)
+                attach: (companion) => this.attachSync(companion, opts),
+                access: (access) => void (this.access = access)
             });
         }
         catch (error) {