edytor 0.1.0-next.24 → 0.1.0-next.25

package/README.md

@@ -15,7 +15,7 @@
 
 Edytor aims to be for Svelte what Slate.js is for React: a heavily customizable editor with an API to build any kind of collaborative rich text editor.
 
-> **Work in progress.** Edytor is a pre-release (`0.1.0-next.24`, `edytor@next` on npm) and not ready for production; the API changes between releases without a compatibility layer. The untagged `edytor@0.0.11` on npm predates the current API. Issues and PRs are welcome: when you report a bug, include the document's JSON value.
+> **Work in progress.** Edytor is a pre-release (`0.1.0-next.25`, `edytor@next` on npm) and not ready for production; the API changes between releases without a compatibility layer. The untagged `edytor@0.0.11` on npm predates the current API. Issues and PRs are welcome: when you report a bug, include the document's JSON value.
 
 ## Features
 

package/dist/cloudflare/DocumentRoom.d.ts

@@ -317,6 +317,12 @@ export type RoomLogEntry = {
     edytor: 'fault';
     reason: 'storage' | 'internal';
     detail: string;
+} | {
+    edytor: 'convert';
+    from: number;
+    to: number;
+    blocks: number;
+    bytes: number;
 };
 /** `pending`: deletes of items the room does not hold yet (they wait for them). */
 type RowKind = 'generation' | 'update' | 'snapshot' | 'pending';
@@ -481,6 +487,10 @@ export declare class AttachedDocument {
     } | {
         kind: 'restored';
         records: number;
+    } | {
+        kind: 'converted';
+        from: number;
+        records: number;
     };
     private nextRecord;
     private updates;
@@ -651,6 +661,18 @@ export declare class AttachedDocument {
      * engine refuses) is refused for good.
      */
     private load;
+    /**
+     * The generation cutover at load (`room.generation.convert`): the
+     * records of a generation-4 container are read as JSON
+     * (`crdt.generations.previousJSON`), which this generation seeds as
+     * `onLoad`'s JSON is (deterministic: every replica converting the same
+     * state writes the same update), and the container is replaced by it in
+     * one storage transaction: rows, replicas, purge epochs, slot editors
+     * and the stored restore go; the document data, the alarm's due tasks
+     * and `lastUpdated` stay. What a generation-4 client never sent is not
+     * in it; history, attribution and CRDT identity do not cross.
+     */
+    private convert;
     /** The bytes of the stored `pending` records (uncompressed, as every record but a snapshot). */
     private pendingBytes;
     /**

package/dist/cloudflare/DocumentRoom.js

@@ -264,17 +264,7 @@ const knob = (value, fallback, max = fallback) => {
     return Number.isInteger(n) && n > 0 ? Math.min(n, max) : fallback;
 };
 /** A semantics config as the facade's lookups — own keys only: block types come off the wire. */
-const lookups = (semantics) => {
-    const own = (table = {}) => (type) => Object.hasOwn(table, type) ? table[type] : undefined;
-    const rendersContent = own(semantics.rendersContent);
-    return {
-        roleOf: own(semantics.roles),
-        kinds: () => Object.keys(semantics.roles ?? {}),
-        defaultChildOf: own(semantics.defaultChild),
-        rendersContent: (type) => rendersContent(type) ?? true,
-        defaultType: semantics.defaultType
-    };
-};
+const lookups = (semantics) => E.facadeConfigOf(semantics);
 const encodeJSON = (value) => new TextEncoder().encode(JSON.stringify(value));
 /** An awareness frame carrying `entries` — no `Awareness` instance involved. */
 export const presenceFrame = (entries) => E.frame(E.messageAwareness, (e) => E.writeVarUint8Array(e, E.writeAwarenessEntries(entries)));
@@ -652,6 +642,8 @@ const roomDoc = (keep) => {
     return doc;
 };
 /** Admit stored or loaded updates into a room document (`prepareRoomDoc`'s collection rules). */
+/** How many blocks `children` holds, nested ones included. */
+const countBlocks = (children) => children.reduce((n, block) => n + 1 + countBlocks(block.children ?? []), 0);
 const admit = (updates, name, keep) => crdt.admission.admitUpdate(updates, name, { prepare: (doc) => prepareRoomDoc(doc, keep) });
 // ── Per-writer marks (H2) ──────────────────────────────────────────
 /** The writer `n` of a per-writer block mark key (`del.<n>`, `wd.<n>`), or `null`. */
@@ -1400,6 +1392,10 @@ export class AttachedDocument {
             }
             const [generation, ...rest] = records;
             const found = JSON.parse(new TextDecoder().decode(generation.bytes));
+            // A container of generation 4 converts through its JSON (`room.generation.convert`).
+            if (generation.kind === 'generation' && E.isPreviousGenerationRecord(found)) {
+                return this.convert(rest);
+            }
             if (generation.kind !== 'generation' || !isGenerationRecord(found)) {
                 throw new E.GenerationMismatchError(`room ${this.ctx.id}`, found);
             }
@@ -1418,6 +1414,57 @@ export class AttachedDocument {
             this.fail(error, false);
         }
     }
+    /**
+     * The generation cutover at load (`room.generation.convert`): the
+     * records of a generation-4 container are read as JSON
+     * (`crdt.generations.previousJSON`), which this generation seeds as
+     * `onLoad`'s JSON is (deterministic: every replica converting the same
+     * state writes the same update), and the container is replaced by it in
+     * one storage transaction: rows, replicas, purge epochs, slot editors
+     * and the stored restore go; the document data, the alarm's due tasks
+     * and `lastUpdated` stay. What a generation-4 client never sent is not
+     * in it; history, attribution and CRDT identity do not cross.
+     */
+    convert(records) {
+        const json = crdt.generations.previousJSON(records.map((record) => (record.v2 ? { v2: record.bytes } : record.bytes)), (doc) => this.facadeOf(doc));
+        const scratch = crdt.createDoc();
+        const facade = this.facadeOf(scratch);
+        facade.seed(json.children, json.data);
+        facade.dispose();
+        const update = Y.encodeStateAsUpdate(scratch);
+        scratch.destroy();
+        const doc = admit(update, `room ${this.ctx.id} conversion`, () => this.restoreKeep);
+        const snapshot = liveState(doc);
+        this.ctx.storage.transactionSync(() => {
+            for (const table of [
+                this.rowsTable,
+                this.replicasTable,
+                this.epochsTable,
+                this.editorsTable,
+                this.restoreTable
+            ])
+                this.sql.exec(`DELETE FROM ${table}`);
+            this.nextRecord = 0;
+            this.insert('snapshot', snapshot);
+            this.touch();
+            for (const replica of stateVector(doc).keys())
+                this.sql.exec(`INSERT OR IGNORE INTO ${this.replicasTable} (replica, user) VALUES (?, '')`, replica);
+        });
+        this.restoreStep = null;
+        this.format = STORED_GENERATION_RECORD.storage;
+        this.documentBytes = snapshot.length;
+        this.updates = 0;
+        this.storedWaiting = Y.createIdSet();
+        this.adopt(doc);
+        this.origin = { kind: 'converted', from: E.PREVIOUS_SCHEMA, records: records.length };
+        this.log({
+            edytor: 'convert',
+            from: E.PREVIOUS_SCHEMA,
+            to: E.SCHEMA_VERSION,
+            blocks: countBlocks(json.children),
+            bytes: snapshot.length
+        });
+    }
     /** The bytes of the stored `pending` records (uncompressed, as every record but a snapshot). */
     pendingBytes() {
         return (this.sql
@@ -1441,7 +1488,7 @@ export class AttachedDocument {
         if (records[0]?.kind === 'generation') {
             try {
                 const found = JSON.parse(new TextDecoder().decode(records[0].bytes));
-                if (isGenerationRecord(found))
+                if (isGenerationRecord(found) || E.isPreviousGenerationRecord(found))
                     format = storageOf(found);
             }
             catch {
@@ -1831,7 +1878,17 @@ export class AttachedDocument {
             return null;
         const bytes = await gunzip(new Uint8Array(value));
         return noTimers(() => {
-            const doc = admit([{ v2: bytes }], `room ${this.ctx.id} version ${key}`, () => null);
+            let doc;
+            try {
+                doc = admit([{ v2: bytes }], `room ${this.ctx.id} version ${key}`, () => null);
+            }
+            catch (error) {
+                // A version written by generation 4 reads through its JSON (`room.generation.convert`).
+                const problem = error.problem;
+                if (problem?.kind !== 'unsupported' || problem.version !== E.PREVIOUS_SCHEMA)
+                    throw error;
+                return crdt.generations.previousJSON([{ v2: bytes }], (d) => this.facadeOf(d));
+            }
             const facade = this.facadeOf(doc);
             try {
                 return facade.toJSON();
@@ -2688,7 +2745,11 @@ export class AttachedDocument {
         if (syncType !== E.messageYjsSyncStep2 && syncType !== E.messageYjsUpdate) {
             return this.refuse(ws, { reason: 'malformed', detail: `sync type ${syncType}` });
         }
-        const update = decode(() => E.readVarUint8Array(decoder));
+        // A SyncStep2 is v2 on the wire (P5): every path below reads v1.
+        const update = decode(() => {
+            const payload = E.readVarUint8Array(decoder);
+            return syncType === E.messageYjsSyncStep2 ? sync.step2Update(payload) : payload;
+        });
         const started = now();
         try {
             this.onUpdate(ws, attachment, doc, update);

package/dist/crdt/data.js

@@ -15,7 +15,8 @@ const itemish = (s) => /^~[a-z]/.test(s);
 export const keySegment = (k) => (k.startsWith('~') ? `~0${k.slice(1)}` : k);
 /** The object key a path segment names (`keySegment`'s inverse). */
 export const segmentKey = (s) => (s.startsWith('~0') ? `~${s.slice(2)}` : s);
-const RANK = /^(?:[-\w]{16})+$/;
+/** A rank's characters (`placement/rank.ts`, P7: variable-length digits, `!` before a tie). */
+const RANK = /^[-\w?!]+$/;
 const index = (k) => (/^(0|[1-9]\d*)$/.test(k) ? Number(k) : -1);
 const rank = (v) => (typeof v === 'string' && RANK.test(v) ? v : undefined);
 /** Item `id`'s place: where a move put it (`id>`), else where it was made (`id#`). */

package/dist/crdt/document.d.ts

@@ -1,3 +1,146 @@
+/**
+ * `EdytorDocument` — the assembled document: one composition/lifecycle
+ * owner binding the production engine once and composing the existing
+ * domain facade, the default local history, one shared awareness, the
+ * document-level semantic configuration (block roles + default type) and
+ * the local actor identity (compact per-block attribution, U1+U2).
+ *
+ * Used headlessly or shared by any number of `Edytor` views:
+ *
+ * ```ts
+ * const document = createDocument({ value, actor: { id: 'user-42', name: 'Ada' } });
+ * document.facade.insertText(bootstrapId, 0, 'hello');
+ * document.history.undo();
+ * const saved = document.encode();
+ * const restored = loadDocument(saved);
+ * ```
+ *
+ * ```svelte
+ * <Edytor {document} />
+ * ```
+ *
+ * ── Owned vs borrowed ──────────────────────────────────────────────────
+ *
+ * `createDocument`/`loadDocument` allocate a FRESH engine doc — the
+ * document owns it and `destroy()` releases everything exactly once
+ * (undo manager, facade/run-view lease, awareness, doc, sync cleanups).
+ * `attachDocument` composes the same services around a doc the CALLER
+ * owns: `destroy()` releases the document-created services but never
+ * `doc.destroy()`s the borrowed doc (borrowing grants no destruction
+ * authority — U1 contract). The same rule applies to an injected
+ * `awareness` (the `_ownsAwareness` convention already used by
+ * `IndexeddbPersistence`).
+ *
+ * ── Readiness ──────────────────────────────────────────────────────────
+ *
+ * `createDocument({ value })` seeds synchronously (local-first) and is
+ * `ready` on return. A document created WITHOUT a value stays `pending`:
+ * no bootstrap is stamped, no version written, because a provider may
+ * still hydrate it. `sync(value?)` is the single explicit readiness
+ * transition — the same deferral `Edytor.sync()` had: assert-and-adopt
+ * on an already-initialized (hydrated) doc, `init` on a still-fresh one,
+ * then the history attaches (bootstrap-before-capture — `createUndoManager`
+ * on the facade keeps that invariant internally too). `loadDocument`
+ * validates the payload BEFORE the facade or any capture attaches, then
+ * arrives ready.
+ *
+ * Per-state legality: `pending` — reads (`facade.project`/`toJSON`),
+ * `attachSync`, `adoptSemantics`, `trackOrigin`, `sync()`, `destroy()`
+ * are legal; `history` throws {@link DocumentNotReadyError}; nothing
+ * 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.)
+ *
+ * ── Admission boundary (U8) ────────────────────────────────────────────
+ *
+ * Every content-entry path crosses the one document-level admission gate
+ * (`src/lib/crdt/admission.ts` — shared vocabulary with the transport
+ * layer's staged-update gate):
+ *
+ * - `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},
+ *   {@link SchemaMismatchError}) leaves nothing composed and never
+ *   touches the caller's bytes;
+ * - `attachDocument` — the borrowed doc is gated BEFORE any composition
+ *   touches it; a refusal leaves it byte-identical (and re-attachable
+ *   once its state heals). It never auto-seeds: the doc always attaches
+ *   `pending` and only `sync()`/migration decides content state;
+ * - `sync()` — re-runs the gate at the readiness decision: provider or
+ *   raw writes may have landed since attach. A doc that fails now
+ *   refuses readiness with the typed error (stays `pending`, content
+ *   preserved) rather than `init` stamping a schema over unversioned
+ *   content; a `'fresh'` verdict seeds (`local`), an `'initialized'`
+ *   verdict adopts (`hydrated`). Idempotent once ready.
+ *
+ * Refusal preserves data — the gate reads are write-free: refused docs
+ * keep their content, refused updates keep their bytes, and provider-side
+ * refusals keep their stored rows (`IndexeddbPersistence` compaction
+ * stays blocked while a refused row set cannot be represented by a
+ * compacted snapshot).
+ *
+ * ── Semantic configuration ─────────────────────────────────────────────
+ *
+ * The adopted capability (rule R5) is document-level state that outlives
+ * any single view: structural roles (`void`/`island`), whether a kind
+ * renders its own content (`rendersContent`), the default child type per
+ * parent type (`defaultChild`) and `defaultType`. Views contribute what
+ * their plugin block definitions declare via {@link adoptSemantics}: the
+ * first declaration for a type is adopted, a later CONFLICTING one is an
+ * error, and a refused contribution adopts nothing (views cannot silently
+ * impose incompatible structural rules on a shared document). Snippets
+ * and DOM hooks stay view-side.
+ *
+ * ── History ────────────────────────────────────────────────────────────
+ *
+ * One registry-scoped `Y.UndoManager` per document (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
+ *   document's own headless origin, `null` (untyped local transactions)
+ *   and every view's `TRANSACTION` instance registered via
+ *   {@link trackOrigin} — each `Edytor` keeps its own instance so the
+ *   mirror can still tell its own commits from a sibling view's, while
+ *   identity tracking keeps undo LOCAL unless the document is actually
+ *   shared.
+ * - `captureTransaction` — `transaction.local !== false`. The engine
+ *   marks every update-integration transaction non-local: `applyUpdate`
+ *   runs `transact(..., local=false)` AND forces `transaction.local =
+ *   false` on the in-flight transaction, so even an apply nested inside
+ *   a local `transact` marks the whole commit non-local. This is the
+ *   remote-exclusion contract: NO provider path or raw
+ *   `applyUpdate(doc, u)` — stamped or originless — can ever enter the
+ *   local user undo stack, and the guarantee cannot be bypassed by a
+ *   provider forgetting to stamp an origin. (Provider paths still stamp
+ *   their instance as origin — required anyway so `doc.on('update')`
+ *   echo suppression keeps working — see `protocols/sync.ts`
+ *   `remoteApplyOrigin` for the residual no-origin default.)
+ *
+ * `null` therefore carries only LOCAL untyped transactions now — direct
+ * `document.facade.<op>` calls outside `document.transact`, raw
+ * `doc.transact(fn)` writes. Keeping it tracked preserves the headless
+ * contract (`document.facade.insertText(...)` stays undoable); callers
+ * wanting per-action undo grouping should prefer `document.transact`.
+ * Bookkeeping writes that must never enter user history run under an
+ * UNTRACKED origin (the undo-ownership repair's `UNDO_REPAIR_ORIGIN`
+ * Symbol and the actor-dictionary's `ATTRIBUTION_ORIGIN` are the existing
+ * examples) or inside a non-local transaction; either channel is
+ * sufficient and both are free of the local undo stack.
+ *
+ * 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`.
+ */
+import type { MarkEdge } from './text/marks.js';
 import type { EngineApi, YDoc, YUndoManager } from './engine-api.js';
 import { type AttributionBinding, type DocumentAttribution } from './attribution/index.js';
 import { type BlockRole, type EdytorDoc, type EdytorDocBinding } from './edytor-doc.js';
@@ -32,6 +175,13 @@ export type DocumentSemanticsConfig = {
     defaultChild?: Record<string, string>;
     /** Default block type — the root's default child and the bootstrap block. */
     defaultType?: string;
+    /**
+     * H5: per mark, its edge (its record's `edge`) — where a concurrent insert
+     * at each end of a mark lands. Undeclared marks are `inclusive`.
+     */
+    marks?: Record<string, {
+        edge?: MarkEdge;
+    }>;
 };
 export type DocumentOptions = {
     /** Local actor — anonymous opaque id when absent. */
@@ -340,6 +490,7 @@ export declare class EdytorDocument {
         roles: Map<string, BlockRole>;
         rendersContent: Map<string, boolean>;
         defaultChild: Map<string, string>;
+        marks: Map<string, MarkEdge>;
     };
     /**
      * The default child type under a parent of `parentType` (`null` = the

package/dist/crdt/document.js

@@ -1,145 +1,3 @@
-/**
- * `EdytorDocument` — the assembled document: one composition/lifecycle
- * owner binding the production engine once and composing the existing
- * domain facade, the default local history, one shared awareness, the
- * document-level semantic configuration (block roles + default type) and
- * the local actor identity (compact per-block attribution, U1+U2).
- *
- * Used headlessly or shared by any number of `Edytor` views:
- *
- * ```ts
- * const document = createDocument({ value, actor: { id: 'user-42', name: 'Ada' } });
- * document.facade.insertText(bootstrapId, 0, 'hello');
- * document.history.undo();
- * const saved = document.encode();
- * const restored = loadDocument(saved);
- * ```
- *
- * ```svelte
- * <Edytor {document} />
- * ```
- *
- * ── Owned vs borrowed ──────────────────────────────────────────────────
- *
- * `createDocument`/`loadDocument` allocate a FRESH engine doc — the
- * document owns it and `destroy()` releases everything exactly once
- * (undo manager, facade/run-view lease, awareness, doc, sync cleanups).
- * `attachDocument` composes the same services around a doc the CALLER
- * owns: `destroy()` releases the document-created services but never
- * `doc.destroy()`s the borrowed doc (borrowing grants no destruction
- * authority — U1 contract). The same rule applies to an injected
- * `awareness` (the `_ownsAwareness` convention already used by
- * `IndexeddbPersistence`).
- *
- * ── Readiness ──────────────────────────────────────────────────────────
- *
- * `createDocument({ value })` seeds synchronously (local-first) and is
- * `ready` on return. A document created WITHOUT a value stays `pending`:
- * no bootstrap is stamped, no version written, because a provider may
- * still hydrate it. `sync(value?)` is the single explicit readiness
- * transition — the same deferral `Edytor.sync()` had: assert-and-adopt
- * on an already-initialized (hydrated) doc, `init` on a still-fresh one,
- * then the history attaches (bootstrap-before-capture — `createUndoManager`
- * on the facade keeps that invariant internally too). `loadDocument`
- * validates the payload BEFORE the facade or any capture attaches, then
- * arrives ready.
- *
- * Per-state legality: `pending` — reads (`facade.project`/`toJSON`),
- * `attachSync`, `adoptSemantics`, `trackOrigin`, `sync()`, `destroy()`
- * are legal; `history` throws {@link DocumentNotReadyError}; nothing
- * 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.)
- *
- * ── Admission boundary (U8) ────────────────────────────────────────────
- *
- * Every content-entry path crosses the one document-level admission gate
- * (`src/lib/crdt/admission.ts` — shared vocabulary with the transport
- * layer's staged-update gate):
- *
- * - `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},
- *   {@link SchemaMismatchError}) leaves nothing composed and never
- *   touches the caller's bytes;
- * - `attachDocument` — the borrowed doc is gated BEFORE any composition
- *   touches it; a refusal leaves it byte-identical (and re-attachable
- *   once its state heals). It never auto-seeds: the doc always attaches
- *   `pending` and only `sync()`/migration decides content state;
- * - `sync()` — re-runs the gate at the readiness decision: provider or
- *   raw writes may have landed since attach. A doc that fails now
- *   refuses readiness with the typed error (stays `pending`, content
- *   preserved) rather than `init` stamping a schema over unversioned
- *   content; a `'fresh'` verdict seeds (`local`), an `'initialized'`
- *   verdict adopts (`hydrated`). Idempotent once ready.
- *
- * Refusal preserves data — the gate reads are write-free: refused docs
- * keep their content, refused updates keep their bytes, and provider-side
- * refusals keep their stored rows (`IndexeddbPersistence` compaction
- * stays blocked while a refused row set cannot be represented by a
- * compacted snapshot).
- *
- * ── Semantic configuration ─────────────────────────────────────────────
- *
- * The adopted capability (rule R5) is document-level state that outlives
- * any single view: structural roles (`void`/`island`), whether a kind
- * renders its own content (`rendersContent`), the default child type per
- * parent type (`defaultChild`) and `defaultType`. Views contribute what
- * their plugin block definitions declare via {@link adoptSemantics}: the
- * first declaration for a type is adopted, a later CONFLICTING one is an
- * error, and a refused contribution adopts nothing (views cannot silently
- * impose incompatible structural rules on a shared document). Snippets
- * and DOM hooks stay view-side.
- *
- * ── History ────────────────────────────────────────────────────────────
- *
- * One registry-scoped `Y.UndoManager` per document (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
- *   document's own headless origin, `null` (untyped local transactions)
- *   and every view's `TRANSACTION` instance registered via
- *   {@link trackOrigin} — each `Edytor` keeps its own instance so the
- *   mirror can still tell its own commits from a sibling view's, while
- *   identity tracking keeps undo LOCAL unless the document is actually
- *   shared.
- * - `captureTransaction` — `transaction.local !== false`. The engine
- *   marks every update-integration transaction non-local: `applyUpdate`
- *   runs `transact(..., local=false)` AND forces `transaction.local =
- *   false` on the in-flight transaction, so even an apply nested inside
- *   a local `transact` marks the whole commit non-local. This is the
- *   remote-exclusion contract: NO provider path or raw
- *   `applyUpdate(doc, u)` — stamped or originless — can ever enter the
- *   local user undo stack, and the guarantee cannot be bypassed by a
- *   provider forgetting to stamp an origin. (Provider paths still stamp
- *   their instance as origin — required anyway so `doc.on('update')`
- *   echo suppression keeps working — see `protocols/sync.ts`
- *   `remoteApplyOrigin` for the residual no-origin default.)
- *
- * `null` therefore carries only LOCAL untyped transactions now — direct
- * `document.facade.<op>` calls outside `document.transact`, raw
- * `doc.transact(fn)` writes. Keeping it tracked preserves the headless
- * contract (`document.facade.insertText(...)` stays undoable); callers
- * wanting per-action undo grouping should prefer `document.transact`.
- * Bookkeeping writes that must never enter user history run under an
- * UNTRACKED origin (the undo-ownership repair's `UNDO_REPAIR_ORIGIN`
- * Symbol and the actor-dictionary's `ATTRIBUTION_ORIGIN` are the existing
- * examples) or inside a non-local transaction; either channel is
- * sufficient and both are free of the local undo stack.
- *
- * 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`.
- */
 import { DEV } from 'esm-env';
 import { Y } from './engine.js';
 import { bindAttribution } from './attribution/index.js';
@@ -313,7 +171,8 @@ export class EdytorDocument {
     _capability = {
         roles: new Map(),
         rendersContent: new Map(),
-        defaultChild: new Map()
+        defaultChild: new Map(),
+        marks: new Map()
     };
     _defaultType;
     _historyOptions;
@@ -337,6 +196,7 @@ export class EdytorDocument {
             defaultType: this._defaultType,
             defaultChildOf: (type) => this._capability.defaultChild.get(type),
             rendersContent: (type) => this.rendersContent(type),
+            markEdge: (mark) => this._capability.marks.get(mark),
             // U1: the facade's block-attribution ops read the actor lazily —
             // `this.actor` is assigned below, after facade construction.
             actor: () => this.actor,
@@ -455,12 +315,13 @@ export class EdytorDocument {
      * copies — mutation is not supported; contribute via {@link adoptSemantics}.
      */
     get semantics() {
-        const { roles, rendersContent, defaultChild } = this._capability;
+        const { roles, rendersContent, defaultChild, marks } = this._capability;
         return {
             defaultType: this._defaultType,
             roles: new Map(roles),
             rendersContent: new Map(rendersContent),
-            defaultChild: new Map(defaultChild)
+            defaultChild: new Map(defaultChild),
+            marks: new Map(marks)
         };
     }
     /**
@@ -498,7 +359,11 @@ export class EdytorDocument {
         const incoming = [
             ['roles', Object.entries(config.roles ?? {}).map(([t, r]) => [t, normalizeRole(r)])],
             ['rendersContent', Object.entries(config.rendersContent ?? {})],
-            ['defaultChild', Object.entries(config.defaultChild ?? {})]
+            ['defaultChild', Object.entries(config.defaultChild ?? {})],
+            [
+                'marks',
+                Object.entries(config.marks ?? {}).map(([mark, m]) => [mark, m?.edge ?? 'inclusive'])
+            ]
         ];
         // Pass 1 — validate EVERYTHING before mutating: a conflicting entry
         // late in a table must not leave earlier entries half-adopted.