@nerd-bible/wordgard 0.0.0-beta3

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (C) 2026 by Marijn Haverbeke <marijn@haverbeke.berlin>.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,24 @@
+# Wordgard
+
+[ [**WEBSITE**](https://wordgard.net/) | [**DOCS**](https://wordgard.net/docs/) | [**ISSUES**](https://code.haverbeke.berlin/wordgard/wordgard/issues) | [**FORUM**](https://discuss.wordgard.net/) ]
+
+This is the [Wordgard](https://wordgard.net) package. It implements a
+rich text editor framework for the browser.
+
+```bash
+npm i wordgard
+```
+
+```javascript
+import {Wordgard, menuBar} from "wordgard/editor"
+import {fullSchema} from "wordgard/schema"
+import {history} from "wordgard/history"
+
+const myEditor = Wordgard.create({
+  parent: document.body,
+  doc: `<h2>Hello World</h2>`,
+  config: [fullSchema(), history(), menuBar()]
+})
+```
+
+This project is licensed under an MIT license.

package/dist/collab.d.ts

@@ -0,0 +1,105 @@
+import { GardState, Correction, Transaction } from 'wordgard/state';
+import { ChangeSet, Plot } from 'wordgard/doc';
+
+/**
+Create an instance of the collaborative editing plugin.
+*/
+declare function collab(config?: collab.Config): GardState.Extension;
+declare namespace collab {
+    /**
+    Options to {@link collab}.
+    */
+    type Config = {
+        /**
+        The starting document version. Defaults to 0.
+        */
+        startVersion?: number;
+        /**
+        This client's identifying {@link collab.getClientID ID}. Will be a
+        randomly generated string if not provided.
+        */
+        clientID?: string;
+        /**
+        A set of corrections to apply to transformed changes. Can be
+        used to enforce document shapes even in merged changes.
+        Requires the exact same set, in the same order, to be used on
+        the server.
+        */
+        corrections?: readonly Correction[];
+        /**
+        It is possible to share information other than document changes
+        through this extension. If you provide this option, your
+        function will be called on each transaction, and the effects it
+        returns will be sent to the server, much like changes are. Such
+        effects are automatically remapped when conflicting remote
+        changes come in.
+        */
+        sharedEffects?: (tr: Transaction) => readonly Transaction.Effect<any>[];
+    };
+    /**
+    An update is a set of changes and effects.
+    */
+    interface Update {
+        /**
+        The document version that this update starts from.
+        */
+        version: number;
+        /**
+        The {@link collab.Config.clientID ID} of the client who
+        created this update.
+        */
+        clientID: string;
+        /**
+        The changes made by this update.
+        */
+        changes: ChangeSet;
+        /**
+        The effects in this update. There'll only ever be effects here
+        when you configure your collab extension with a {@link
+        collab.Config.sharedEffects `sharedEffects`} option.
+        */
+        effects?: readonly Transaction.Effect<unknown>[];
+    }
+    /**
+    Create a transaction that represents a set of new updates received
+    from the authority. Applying this transaction moves the state
+    forward to, for remote changes, integrate them into our local
+    state, and for our own changes, drop them from the set of
+    unconfirmed local changes.
+    */
+    function receive(state: GardState, updates: readonly collab.Update[]): Transaction;
+    /**
+    If there are unconfirmed local changes that need to be sent to the
+    server,return them as an `Update` object.
+    */
+    function sendableUpdate(state: GardState): collab.Update | null;
+    /**
+    Returns true if there are unconfirmed changes for this editor.
+    */
+    function hasUnsentUpdate(state: GardState): boolean;
+    /**
+    Get the version up to which the collab plugin has synced with the
+    central authority.
+    */
+    function getSyncedVersion(state: GardState): number;
+    /**
+    Get this editor's collaborative editing client ID.
+    */
+    function getClientID(state: GardState): string;
+    /**
+    Transform an update that arrives on the server with an outdated
+    start version. Being able to do this requires tracking a
+    document history server-side. It is not necessary to do this,
+    but it helps a lot with “starvation” problems, where slower
+    clients or clients with a high ping can, in a busy document,
+    keep losing the race to submit their changes to other, faster
+    clients.
+    */
+    function transformUpdate(update: collab.Update, over: readonly {
+        doc: Plot.Doc;
+        changes: ChangeSet;
+        clientID: string;
+    }[], corrections?: readonly Correction[]): collab.Update | null;
+}
+
+export { collab };

package/dist/collab.js

@@ -0,0 +1,218 @@
+import { GardState, Transaction, Correction } from 'wordgard/state';
+import { ChangeSet } from 'wordgard/doc';
+
+class LocalUpdate {
+    changes;
+    effects;
+    constructor(changes, effects) {
+        this.changes = changes;
+        this.effects = effects;
+    }
+}
+function addUpdate(to, changes, effects = []) {
+    if (changes.empty && !effects.length)
+        return to;
+    if (!to)
+        return new LocalUpdate(changes, effects);
+    return new LocalUpdate(to.changes.compose(changes), Transaction.Effect.mapEffects(to.effects, changes).concat(effects));
+}
+function mapOpenUpdate(update, doc, over, accum) {
+    let { a, b } = ChangeSet.transform(doc, over, update.changes);
+    return [new LocalUpdate(b, Transaction.Effect.mapEffects(update.effects, a)), accum.compose(a)];
+}
+class CollabState {
+    version;
+    syncedDoc;
+    nextUpdate;
+    openUpdate;
+    constructor(
+    version, 
+    syncedDoc, 
+    nextUpdate, 
+    openUpdate) {
+        this.version = version;
+        this.syncedDoc = syncedDoc;
+        this.nextUpdate = nextUpdate;
+        this.openUpdate = openUpdate;
+    }
+}
+const collabConfig = /*@__PURE__*/GardState.Facet.define({
+    combine(configs) {
+        let combined = GardState.Facet.combineConfig(configs, {
+            startVersion: 0,
+            clientID: null,
+            sharedEffects: () => [],
+            corrections: []
+        }, {
+            generatedID: a => a
+        });
+        if (combined.clientID == null)
+            combined.clientID = (configs.length && configs[0].generatedID) || "";
+        return combined;
+    }
+});
+const collabReceive = /*@__PURE__*/Transaction.Effect.define({
+    map(state, changes) {
+        return changes.empty ? state
+            : new CollabState(state.version, state.syncedDoc, state.nextUpdate, addUpdate(state.openUpdate, changes));
+    }
+});
+const collabField = /*@__PURE__*/GardState.Field.define({
+    create(state) {
+        return new CollabState(state.facet(collabConfig).startVersion, state.doc, null, null);
+    },
+    update(collab, tr) {
+        for (let e of tr.effects)
+            if (e.is(collabReceive))
+                return e.value;
+        let { sharedEffects } = tr.startState.facet(collabConfig);
+        let effects = sharedEffects(tr);
+        if (effects.length || !tr.changes.empty)
+            return new CollabState(collab.version, collab.syncedDoc, collab.nextUpdate, addUpdate(collab.openUpdate, tr.changes, effects));
+        return collab;
+    }
+});
+function collab(config = {}) {
+    return [collabField, collabConfig.of({ generatedID: Math.floor(Math.random() * 1e9).toString(36), ...config })];
+}
+;collab = /*@__PURE__*/(function (collab_1) {
+    function receive(state, updates) {
+        let { version, syncedDoc, nextUpdate, openUpdate } = state.field(collabField);
+        let { clientID, corrections } = state.facet(collabConfig);
+        let changes = ChangeSet.empty(state.doc.length);
+        let effects = [];
+        let haveRemote = false;
+        for (let update of updates) {
+            if (update.version != version)
+                throw new Error("Version mismatch in in received collab update");
+            if (update.clientID == clientID) {
+                if (!nextUpdate)
+                    throw new Error("Received unknown update with our client ID");
+                syncedDoc = (openUpdate || haveRemote) ? nextUpdate.changes.apply(syncedDoc) : state.doc;
+                mismatch: if (!nextUpdate.changes.eq(update.changes)) {
+                    if (haveRemote && nextUpdate && corrections.length) {
+                        let correct = Correction.check(nextUpdate.changes, syncedDoc, corrections);
+                        if (correct && nextUpdate.changes.compose(correct).eq(update.changes)) {
+                            if (openUpdate)
+                                [openUpdate, changes] = mapOpenUpdate(openUpdate, syncedDoc, correct, changes);
+                            else
+                                changes = changes.compose(correct);
+                            syncedDoc = correct.apply(syncedDoc);
+                            break mismatch;
+                        }
+                    }
+                    throw new Error("Received update with our client ID doesn't match our own local update");
+                }
+                nextUpdate = null;
+            }
+            else {
+                let newChanges = update.changes, newEffects = update.effects || [];
+                let baseDoc = syncedDoc;
+                if (nextUpdate) {
+                    let { a, b } = ChangeSet.transform(baseDoc, newChanges, nextUpdate.changes);
+                    if (openUpdate)
+                        baseDoc = nextUpdate.changes.apply(baseDoc);
+                    nextUpdate = new LocalUpdate(b, Transaction.Effect.mapEffects(nextUpdate.effects, a));
+                    newChanges = a;
+                    newEffects = Transaction.Effect.mapEffects(newEffects, b);
+                }
+                if (openUpdate) {
+                    let { a, b } = ChangeSet.transform(baseDoc, newChanges, openUpdate.changes);
+                    openUpdate = new LocalUpdate(b, Transaction.Effect.mapEffects(openUpdate.effects, a));
+                    newChanges = a;
+                    newEffects = Transaction.Effect.mapEffects(newEffects, b);
+                }
+                changes = changes.compose(newChanges);
+                effects = Transaction.Effect.mapEffects(effects, newChanges).concat(newEffects);
+                syncedDoc = update.changes.apply(syncedDoc);
+                haveRemote = true;
+            }
+            version++;
+        }
+        if (haveRemote && corrections.length) {
+            let base = syncedDoc;
+            if (nextUpdate) {
+                base = nextUpdate.changes.apply(base);
+                let correct = Correction.check(nextUpdate.changes, base, corrections);
+                if (correct) {
+                    nextUpdate = addUpdate(nextUpdate, correct);
+                    if (openUpdate) {
+                        [openUpdate, changes] = mapOpenUpdate(openUpdate, base, correct, changes);
+                        base = correct.apply(base);
+                    }
+                    else {
+                        changes = changes.compose(correct);
+                    }
+                }
+            }
+            if (openUpdate) {
+                base = openUpdate.changes.apply(base);
+                let correct = Correction.check(openUpdate.changes, base, corrections);
+                if (correct) {
+                    openUpdate = addUpdate(openUpdate, correct);
+                    changes = changes.compose(correct);
+                }
+            }
+        }
+        return state.update({
+            changes,
+            effects: effects.concat(collabReceive.of(new CollabState(version, syncedDoc, nextUpdate, openUpdate))),
+            annotations: [Transaction.addToHistory.of(false), Transaction.remote.of(true)],
+        });
+    }
+    collab_1.receive = receive;
+    function sendableUpdate(state) {
+        let collab = state.field(collabField);
+        if (!collab.nextUpdate) {
+            if (!collab.openUpdate)
+                return null;
+            collab.nextUpdate = collab.openUpdate;
+            collab.openUpdate = null;
+        }
+        return {
+            version: collab.version,
+            clientID: getClientID(state),
+            changes: collab.nextUpdate.changes,
+            effects: collab.nextUpdate.effects
+        };
+    }
+    collab_1.sendableUpdate = sendableUpdate;
+    function hasUnsentUpdate(state) {
+        let collab = state.field(collabField);
+        return !!(collab.nextUpdate || collab.openUpdate);
+    }
+    collab_1.hasUnsentUpdate = hasUnsentUpdate;
+    function getSyncedVersion(state) {
+        return state.field(collabField).version;
+    }
+    collab_1.getSyncedVersion = getSyncedVersion;
+    function getClientID(state) {
+        return state.facet(collabConfig).clientID;
+    }
+    collab_1.getClientID = getClientID;
+    function transformUpdate(update, over, corrections) {
+        if (!over.length)
+            return update;
+        let { clientID, version, changes, effects } = update;
+        for (let other of over) {
+            if (other.clientID == clientID)
+                return null;
+            if (effects && effects.length)
+                effects = Transaction.Effect.mapEffects(effects, other.changes.transform(other.doc, changes, true));
+            changes = changes.transform(other.doc, other.changes);
+            version++;
+        }
+        if (corrections && corrections.length) {
+            let corrected = Correction.check(changes, changes.apply(over[over.length - 1].doc), corrections);
+            if (corrected) {
+                changes = changes.compose(corrected);
+                if (effects)
+                    effects = Transaction.Effect.mapEffects(effects, corrected);
+            }
+        }
+        return { clientID, version, changes, effects };
+    }
+    collab_1.transformUpdate = transformUpdate;
+;return collab})(collab);
+
+export { collab };