sygnal 7.0.0 → 7.2.0-preview.0

package/dist/yjs.cjs.js

@@ -0,0 +1,923 @@
+'use strict';
+
+var Y = require('yjs');
+var sygnal = require('sygnal');
+var fractionalIndexing = require('fractional-indexing');
+
+function _interopNamespaceDefault(e) {
+    var n = Object.create(null);
+    if (e) {
+        Object.keys(e).forEach(function (k) {
+            if (k !== 'default') {
+                var d = Object.getOwnPropertyDescriptor(e, k);
+                Object.defineProperty(n, k, d.get ? d : {
+                    enumerable: true,
+                    get: function () { return e[k]; }
+                });
+            }
+        });
+    }
+    n.default = e;
+    return Object.freeze(n);
+}
+
+var Y__namespace = /*#__PURE__*/_interopNamespaceDefault(Y);
+
+/*
+ * 'sygnal/yjs' (research: dev-plans/research/crdt-state): the mapping between a plain JSON state
+ * slice and a Yjs document.
+ *
+ * Inferred from the value unless a `shape` declares it (shared({ shape }), D: Q1):
+ * - a plain object                          -> Y.Map (one LWW register per key)
+ * - an array of objects that all have `id`  -> a *collection*: a Y.Map keyed by String(id), each item a
+ *   Y.Map of its fields plus `$o`, a fractional order key (`fractional-indexing`); the array is the
+ *   items sorted by ($o, id). Concurrent add / edit / move / delete of different items merge; a move
+ *   is one register write, so it never duplicates or drops an item, and an edit to a moved item
+ *   survives the move. An empty array is ambiguous: a collection unless the field already holds a
+ *   list (or the shape says 'list'); without a shape the driver warns once (SYG261, dev).
+ * - any other array                         -> Y.Array of JSON values (spliced by common prefix / suffix)
+ * - a string field named in `text` / 'text' in the shape -> Y.Text (character-level merge)
+ * - anything else                           -> a JSON value in its parent (LWW)
+ *
+ * write(y, prev, next) turns the *local* change prev -> next into Yjs operations. It is a 3-way
+ * write: keys / items the local change didn't touch are left alone even when Yjs holds newer remote
+ * values for them, and every write is idempotent against the document's current content (a value
+ * Yjs already holds isn't written again), so a prev older than the document never reverts or
+ * duplicates a remote change. Items that are the same object as before are skipped without a
+ * lookup (index identity first).
+ *
+ * read(y, path, prev, dirty) reads the slice; with `dirty` (the types a transaction changed) it
+ * re-reads only those and keeps prev's objects everywhere else (incremental read).
+ */
+const isPlain = (v) => v !== null && typeof v == 'object' && Object.getPrototypeOf(v) === Object.prototype;
+const hasId = (v) => isPlain(v) && (typeof v.id == 'string' || typeof v.id == 'number');
+const isCollMap = (y) => y instanceof Y__namespace.Map && y.get('$c') === 1;
+const same = (a, b) => a === b || JSON.stringify(a) === JSON.stringify(b);
+// ---- shapes ------------------------------------------------------------------------------------
+const COLL = Symbol.for('sygnal.yjs.collection');
+const KINDS = { text: 't', list: 'l', collection: 'c', map: 'm', value: 'v' };
+/** shape: { items: collection({ text: 'text' }) }: an id-keyed collection whose items have these field shapes */
+const collection = (item = {}) => ({ [COLL]: item });
+/** a public shape ({ title: 'text', items: collection(...), tags: 'list' }) as nodes */
+const normShape = (s) => {
+    if (s == null)
+        return undefined;
+    if (typeof s == 'string') {
+        if (!KINDS[s])
+            throw new TypeError(`shared(): unknown shape '${s}'; use 'text', 'list', 'collection', 'map', 'value', collection({ ... }) or an object of fields`);
+        return { k: KINDS[s] };
+    }
+    if (s[COLL])
+        return { k: 'c', i: fields(s[COLL]) };
+    if (isPlain(s))
+        return { k: 'm', f: fields(s) };
+    throw new TypeError('shared(): a shape is a string, collection({ ... }) or an object of fields');
+};
+const fields = (o) => {
+    const f = {};
+    for (const k in o)
+        f[k] = normShape(o[k]);
+    return f;
+};
+// the item shape of a collection field as a map node (its fields)
+const itemNode = (sh) => sh?.i ? { k: 'm', f: sh.i } : undefined;
+// ---- fractional order keys -----------------------------------------------------------------------
+// a key generateKeyBetween accepts (its default base-62 format: a head letter giving the integer
+// part's length, 'a' 2 .. 'z' 27 and 'Z' 2 .. 'A' 27, then digits; no fraction ending in '0'); any
+// other value (an older document's key) is rekeyed
+const B62 = /^[0-9A-Za-z]+$/;
+const valid = (k) => {
+    if (typeof k != 'string' || !B62.test(k))
+        return false;
+    const c = k.charCodeAt(0), n = c >= 97 ? c - 95 : c <= 90 && c >= 65 ? 92 - c : 0;
+    return n > 0 && k.length >= n && (k.length == n || k[k.length - 1] != '0') && !/^A0{26}/.test(k);
+};
+const splice = (a, b, eq) => {
+    let i = 0, j = 0;
+    while (i < a.length && i < b.length && eq(a[i], b[i]))
+        i++;
+    while (j < a.length - i && j < b.length - i && eq(a[a.length - 1 - j], b[b.length - 1 - j]))
+        j++;
+    return { i, del: a.length - i - j, ins: b.slice(i, b.length - j) };
+};
+/**
+ * The local splice prev -> next, moved onto a document whose content `cur` differs from prev by a
+ * remote splice: shifted when it lies after the remote one, kept when before; an overlapping edit
+ * is clamped (approximate; exact when the document matches either side).
+ */
+const rebase = (l, prev, cur, eq) => {
+    const r = splice(prev, cur, eq);
+    if (l.i + l.del <= r.i)
+        return l;
+    if (l.i >= r.i + r.del)
+        return { ...l, i: l.i + r.ins.length - r.del };
+    const i = Math.min(l.i, r.i);
+    return { i, del: Math.max(0, Math.min(l.del, cur.length - i)), ins: l.ins };
+};
+// eq compares elements (characters, list values)
+const spliceInto = (cur, prev, next, eq, apply) => {
+    const all = (a, b) => a === b || a.length === b.length && splice(a, b, eq).del === 0;
+    if (all(cur, next))
+        return; // already there (a remote change, or no change)
+    const l = splice(prev, next, eq);
+    apply(all(cur, prev) ? l : rebase(l, prev, cur, eq));
+};
+const strEq = (a, b) => a === b;
+const kindOf = (k, n, cur, o, sh, name) => {
+    const d = sh?.k;
+    if (d == 't' && typeof n == 'string' || d == 'l' && Array.isArray(n) || d == 'm' && isPlain(n) || d == 'v')
+        return d;
+    if (d == 'c' && Array.isArray(n) && n.every(hasId))
+        return 'c';
+    if (typeof n == 'string' && o.text?.includes(k))
+        return 't';
+    if (Array.isArray(n) && n.every(hasId)) {
+        if (n.length)
+            return 'c';
+        if (cur == 'l' || cur == 'c')
+            return cur;
+        // an empty array the shape doesn't name: a guess (a collection); a list stays a list
+        if (!d)
+            o.ambiguous?.(name);
+        return 'c';
+    }
+    return isPlain(n) ? 'm' : Array.isArray(n) ? 'l' : 'v';
+};
+const nestedKind = (y) => y instanceof Y__namespace.Text ? 't' : isCollMap(y) ? 'c' : y instanceof Y__namespace.Map ? 'm' : y instanceof Y__namespace.Array ? 'l' : undefined;
+const rootOf = (doc, name, k) => k == 't' ? doc.getText(name + '#t') : k == 'l' ? doc.getArray(name + '#l') : doc.getMap(name + '#' + k);
+const clear = (t) => {
+    if (t instanceof Y__namespace.Map)
+        for (const k of [...t.keys()])
+            t.delete(k);
+    else if (t.length)
+        t.delete(0, t.length);
+};
+const marker = (v) => isPlain(v) && typeof v.$y == 'string' ? v.$y : undefined;
+/** the local change prev -> next of a map (the slice: writeMap(doc.getMap(key), last, value, o, key, shape)) */
+const writeMap = (y, prev, next, o, path, sh, label = path || '') => {
+    prev = isPlain(prev) ? prev : {};
+    for (const k in prev)
+        if (!(k in next) && y.has(k)) {
+            const m = path != null && marker(y.get(k));
+            if (m)
+                clear(rootOf(y.doc, path + '.' + k, m));
+            y.delete(k);
+        }
+    for (const k in next)
+        if (!(k in prev) || prev[k] !== next[k] || !y.has(k))
+            writeValue(y, k, prev[k], next[k], o, path, sh?.f?.[k], label + '.' + k);
+};
+const writeValue = (y, k, p, n, o, path, sh, label) => {
+    const cur = y.get(k), name = path != null ? path + '.' + k : undefined;
+    const had = name != null ? marker(cur) : nestedKind(cur), want = kindOf(k, n, had, o, sh, label);
+    let t;
+    if (name != null) {
+        if (had && had != want)
+            clear(rootOf(y.doc, name, had));
+        if (want == 'v') {
+            if (!same(cur, n))
+                y.set(k, n);
+            return;
+        }
+        if (had != want) {
+            y.set(k, { $y: want });
+            p = undefined;
+        }
+        t = rootOf(y.doc, name, want);
+    }
+    else {
+        if (want == 'v') {
+            if (!same(cur, n))
+                y.set(k, n);
+            return;
+        }
+        if (had != want) {
+            t = want == 't' ? new Y__namespace.Text() : want == 'l' ? new Y__namespace.Array() : new Y__namespace.Map();
+            y.set(k, t);
+            if (want == 'c')
+                t.set('$c', 1);
+            p = undefined;
+        }
+        else
+            t = cur;
+    }
+    if (want == 't') {
+        const s = t.toString();
+        spliceInto(s, typeof p == 'string' ? p : s, n, strEq, ({ i, del, ins }) => { if (del)
+            t.delete(i, del); if (ins)
+            t.insert(i, ins); });
+    }
+    else if (want == 'c')
+        writeColl(t, Array.isArray(p) ? p : [], n, o, itemNode(sh), label);
+    else if (want == 'm')
+        writeMap(t, p, n, o, name, sh, label);
+    else {
+        const c = t.toArray();
+        spliceInto(c, Array.isArray(p) ? p : c, n, same, ({ i, del, ins }) => { if (del)
+            t.delete(i, del); if (ins.length)
+            t.insert(i, ins); });
+    }
+};
+/** a collection: removed ids deleted, new ones added, changed ones written field by field, then order */
+const writeColl = (m, prev, next, o, sh, label) => {
+    const item = (x, p) => {
+        if (p === x)
+            return;
+        const id = String(x.id), it = m.get(id);
+        if (it instanceof Y__namespace.Map) {
+            if (p !== x)
+                writeMap(it, p ?? readItem(it), x, o, undefined, sh, label + '[]');
+        }
+        // new here. An id this side knew that is gone from the document was deleted remotely while it
+        // was edited here: the delete wins (no resurrection)
+        else if (!p) {
+            const im = new Y__namespace.Map();
+            m.set(id, im);
+            writeMap(im, {}, x, o, undefined, sh, label + '[]');
+        }
+    };
+    // the common case (an edit, a toggle): the same ids in the same order. Unchanged items (the same
+    // object) are skipped by index, no maps are built and the order is left alone
+    if (prev.length == next.length && prev.every((x, i) => x === next[i] || x.id === next[i].id)) {
+        for (let i = 0; i < next.length; i++)
+            if (prev[i] !== next[i])
+                item(next[i], prev[i]);
+        return;
+    }
+    // items added (an add, a paste) and nothing else moved: only the new items get keys, between
+    // their neighbours' (the keys order() would give them)
+    if (next.length > prev.length) {
+        const added = [];
+        let j = 0;
+        for (let i = 0; i < next.length; i++) {
+            if (j < prev.length && next[i].id === prev[j].id)
+                item(next[i], prev[j++]);
+            else
+                added.push(i);
+        }
+        if (j == prev.length) {
+            for (const i of added)
+                item(next[i], undefined);
+            if (insertKeys(m, next, added))
+                return;
+            return order(m, next);
+        }
+    }
+    const was = new Map(prev.map((x) => [String(x.id), x])), now = new Set(next.map((x) => String(x.id)));
+    for (const id of was.keys())
+        if (!now.has(id) && m.has(id))
+            m.delete(id);
+    for (const x of next)
+        item(x, was.get(String(x.id)));
+    // the ids or their order changed here (a local edit never reorders, even when the document holds
+    // a remote move this side hasn't seen); removals alone leave the others' order as it was
+    let j = 0;
+    for (const x of prev)
+        if (j < next.length && x.id === next[j].id)
+            j++;
+    if (j < next.length)
+        order(m, next);
+};
+// keys for the items at `added` (indexes in next) between their neighbours' keys; false when a
+// neighbour's key is missing or out of order here (a remote move): order() then sorts it out
+const insertKeys = (m, next, added) => {
+    const keyAt = (i) => m.get(String(next[i].id))?.get('$o');
+    for (let a = 0; a < added.length; a++) {
+        const i = added[a], it = m.get(String(next[i].id));
+        if (!(it instanceof Y__namespace.Map))
+            continue;
+        let lo = null, hi = null;
+        for (let k = i - 1; k >= 0 && lo == null; k--) {
+            const v = keyAt(k);
+            if (v !== undefined) {
+                if (!valid(v))
+                    return false;
+                lo = v;
+            }
+        }
+        // the next item that isn't new (new ones after this one get keys after it)
+        for (let k = i + 1, b = a + 1; k < next.length; k++) {
+            if (b < added.length && added[b] == k) {
+                b++;
+                continue;
+            }
+            const v = keyAt(k);
+            if (v === undefined)
+                continue;
+            if (!valid(v))
+                return false;
+            hi = v;
+            break;
+        }
+        if (lo != null && hi != null && lo >= hi)
+            return false;
+        const cur = it.get('$o');
+        if (!(valid(cur) && (lo == null || cur > lo) && (hi == null || cur < hi)))
+            it.set('$o', fractionalIndexing.generateKeyBetween(lo, hi));
+    }
+    return true;
+};
+/**
+ * The order keys: the longest run of items whose current keys already increase in `next`'s order
+ * stays; every other item gets a key between its neighbours (fractional-indexing; deterministic, so
+ * two clients seeding the same ids write the same keys). Idempotent: an order the document already
+ * has writes nothing; one move writes one key.
+ */
+const order = (m, next) => {
+    const items = next.map((x) => m.get(String(x.id))).filter((it) => it instanceof Y__namespace.Map);
+    const keys = items.map((it) => { const k = it.get('$o'); return valid(k) ? k : undefined; });
+    const keep = lis(keys);
+    let last = null;
+    items.forEach((it, i) => {
+        if (keep.has(i)) {
+            last = keys[i];
+            return;
+        }
+        let hi = null;
+        for (let j = i + 1; j < items.length; j++)
+            if (keep.has(j) && (last == null || keys[j] > last)) {
+                hi = keys[j];
+                break;
+            }
+        last = fractionalIndexing.generateKeyBetween(last, hi);
+        it.set('$o', last);
+    });
+};
+/** indexes of a longest strictly increasing subsequence (undefined keys never kept) */
+const lis = (keys) => {
+    const tails = [], prev = [];
+    keys.forEach((k, i) => {
+        if (k === undefined)
+            return;
+        let lo = 0, hi = tails.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            keys[tails[mid]] < k ? lo = mid + 1 : hi = mid;
+        }
+        prev[i] = lo ? tails[lo - 1] : -1;
+        tails[lo] = i;
+    });
+    const out = new Set();
+    for (let i = tails.length ? tails[tails.length - 1] : -1; i >= 0; i = prev[i])
+        out.add(i);
+    return out;
+};
+const dirtyHere = (y, path, d) => {
+    if (d.types.has(y))
+        return true;
+    if (path != null)
+        for (const n of d.roots)
+            if (n.startsWith(path + '.'))
+                return true;
+    return false;
+};
+/**
+ * A slice's JSON: read(doc.getMap(key), key). With `d` and `prev` (the previous read), only what
+ * the transaction changed is read again; everything else is prev's object.
+ */
+const read = (y, path, prev, d) => {
+    if (!(y instanceof Y__namespace.AbstractType))
+        return y;
+    if (d && prev !== undefined && !dirtyHere(y, path, d))
+        return prev;
+    if (y instanceof Y__namespace.Text)
+        return y.toString();
+    if (y instanceof Y__namespace.Array)
+        return reconcile(prev, y.toArray().map((v) => read(v)));
+    if (y instanceof Y__namespace.Map) {
+        if (isCollMap(y))
+            return readColl(y, d && Array.isArray(prev) ? prev : undefined, d);
+        const out = {}, p = d && isPlain(prev) ? prev : undefined;
+        y.forEach((v, k) => {
+            const m = path != null && marker(v);
+            out[k] = !m ? read(v, undefined, p?.[k], d)
+                : m == 'c' ? readColl(rootOf(y.doc, path + '.' + k, m), d && Array.isArray(p?.[k]) ? p[k] : undefined, d)
+                    : read(rootOf(y.doc, path + '.' + k, m), path + '.' + k, p?.[k], d);
+        });
+        // the fields were read against p's: p itself when every one is p's
+        if (!p)
+            return out;
+        let n = 0;
+        for (const k in out)
+            if (out[k] !== p[k] || !(k in p))
+                return out;
+            else
+                n++;
+        return n == Object.keys(p).length ? p : out;
+    }
+    return y;
+};
+const byKey = (a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0;
+const readColl = (y, prev, d) => {
+    if (!d || !prev) {
+        const items = [];
+        y.forEach((v, k) => { if (v instanceof Y__namespace.Map)
+            items.push([v.get('$o') ?? '', k, v]); });
+        return items.sort(byKey).map(([, , v]) => readItem(v));
+    }
+    if (!d.types.has(y))
+        return prev;
+    // ids to place again (added, removed, replaced, or a new order key) and items edited in place
+    const place = new Set(), edited = new Set();
+    for (const k of d.changed.get(y) || [])
+        if (k != null)
+            place.add(k);
+    for (const t of d.types)
+        if (t._item?.parent === y && t._item.parentSub != null) {
+            const id = t._item.parentSub;
+            if (d.changed.get(t)?.has('$o'))
+                place.add(id);
+            else
+                edited.add(id);
+        }
+    // prev is sorted by ($o, id): the items that stay keep their order; the placed ones go in by binary search
+    const was = new Map(), out = [];
+    for (const x of prev) {
+        const id = String(x.id);
+        if (place.has(id))
+            was.set(id, x);
+        else
+            out.push(edited.has(id) ? readItem(y.get(id), x, d) : x);
+    }
+    if (place.size) {
+        const key = (x) => [y.get(String(x.id))?.get('$o') ?? '', String(x.id)];
+        const ins = [];
+        for (const id of place) {
+            const v = y.get(id);
+            if (v instanceof Y__namespace.Map)
+                ins.push([v.get('$o') ?? '', id, v]);
+        }
+        for (const e of ins.sort(byKey)) {
+            let lo = 0, hi = out.length;
+            while (lo < hi) {
+                const mid = (lo + hi) >> 1;
+                byKey(key(out[mid]), e) < 0 ? lo = mid + 1 : hi = mid;
+            }
+            out.splice(lo, 0, readItem(e[2], was.get(e[1]), d));
+        }
+    }
+    return out.length == prev.length && out.every((x, i) => x === prev[i]) ? prev : out;
+};
+const readItem = (it, prev, d) => {
+    const x = {};
+    it.forEach((v, k) => { if (k != '$o')
+        x[k] = read(v, undefined, prev?.[k], d); });
+    return prev ? reconcile(prev, x) : x;
+};
+/** next, reusing prev's objects wherever they are deep-equal (Collection items keep their identity) */
+const reconcile = (prev, next) => {
+    if (prev === next)
+        return prev;
+    if (Array.isArray(next)) {
+        if (!Array.isArray(prev))
+            return next;
+        let byId;
+        let changed = prev.length != next.length;
+        const out = next.map((x, i) => {
+            // index first; by id only when the items moved
+            let p = prev[i];
+            if (x === p)
+                return p;
+            if (hasId(x) && !(hasId(p) && p.id === x.id))
+                p = (byId || (byId = new Map(prev.filter(hasId).map((y) => [y.id, y])))).get(x.id);
+            const r = reconcile(p, x);
+            if (r !== prev[i])
+                changed = true;
+            return r;
+        });
+        return changed ? out : prev;
+    }
+    if (isPlain(next)) {
+        if (!isPlain(prev))
+            return next;
+        let changed = Object.keys(prev).length != Object.keys(next).length;
+        const out = {};
+        for (const k in next) {
+            out[k] = reconcile(prev[k], next[k]);
+            if (out[k] !== prev[k] || !(k in prev))
+                changed = true;
+        }
+        return changed ? out : prev;
+    }
+    return Object.is(prev, next) ? prev : next;
+};
+
+/*
+ * 'sygnal/yjs' (research: dev-plans/research/crdt-state): makeYjsDriver, the driver that owns a Y.Doc
+ * for `shared()` slices.
+ *
+ *   const drivers = { SHARED: makeYjsDriver({ doc, provider, text: ['text'] }) }
+ *
+ * Sink commands (data, from model entries):
+ *   { key, value, shape?, seed? }   state[key]'s new value (shared()'s `key.LOCAL`, coalesced per flush)
+ *   { undo: key } / { redo: key }   this client's own changes to state[key] (a Y.UndoManager per slice)
+ *   { key, value, step }            (sygnal/canvas history()) a new `step` closes this client's undo
+ *                                   step after the write; while steps come, edits merge by step, not by time
+ *   { presence: { ... } }           this client's awareness state (merged)
+ *   { connect: boolean }            provider.connect() / provider.disconnect() (go offline and back)
+ * Sources: remote(key) ({ value, base }), presence() (the other clients), history(key)
+ * ({ canUndo, canRedo }), doc.
+ *
+ * - Local: the new value is diffed against the last one the driver saw and written in one
+ *   transaction (mapping.ts writeMap, a 3-way idempotent write).
+ * - Remote: every transaction from elsewhere (a peer, a sync, an undo) updates the driver's mirror of
+ *   the slice incrementally (only the types it changed are read again) and emits { value, base };
+ *   shared()'s REMOTE reducer applies it only while state[key] is still `base`.
+ * - Seeding (Q3): `seed: 'whenSynced'` (default) waits for the provider's first sync, then seeds an
+ *   empty document from the app's value, or else takes the document's content (writing any edits
+ *   the app made before the sync onto it). `seed: 'ifEmpty'` seeds at once (a local-only document).
+ *   Without `provider` / `synced` the document counts as synced.
+ */
+const report = (code, message, fix, data) => {
+    try {
+        globalThis.__SYGNAL_DIAGNOSTICS__?.report(code, { severity: 'warn', message, fix, data });
+    }
+    catch (e) {
+        queueMicrotask(() => { throw e; });
+    }
+};
+// the promise of a provider's first sync; null: synced now
+const syncedOf = (o) => {
+    if (o.synced)
+        return o.synced;
+    const p = o.provider;
+    if (!p || p.synced === true || p.isSynced === true)
+        return null;
+    if (p.whenSynced?.then)
+        return p.whenSynced;
+    if (typeof p.on != 'function')
+        return null;
+    return new Promise((r) => {
+        // y-websocket: 'sync' (true); y-webrtc: 'synced' ({ synced }); Hocuspocus: 'synced' ({ state })
+        const f = (x) => {
+            if (x === false || x?.synced === false || x?.state === false)
+                return;
+            for (const e of ['sync', 'synced'])
+                p.off?.(e, f);
+            r();
+        };
+        for (const e of ['sync', 'synced'])
+            p.on(e, f);
+    });
+};
+const makeYjsDriver = (o) => (sink$) => {
+    const { doc } = o, provider = o.provider, awareness = o.awareness ?? provider?.awareness;
+    const local = {}, seed = {}, slices = new Map(), warned = new Set();
+    const opts = {
+        text: o.text,
+        ambiguous: (path) => {
+            if (warned.has(path))
+                return;
+            warned.add(path);
+            report('SYG261', `shared(): '${path}' is an empty array, so its kind is a guess: an id-keyed collection. A list of plain values would be stored as a collection until it has items`, `Declare it: shared({ shape: { ${path.split('.').pop()}: 'list' } }) for plain values, or collection() for items with an id`, { path });
+        },
+    };
+    const first = syncedOf(o);
+    let synced = !first;
+    first?.then(() => {
+        synced = true;
+        for (const s of slices.values())
+            if (!s.started && s.first !== undefined)
+                start(s);
+    });
+    // the root-level types' names (doc.share), by type. Read again on a miss: a type that arrived in
+    // an update is a placeholder until its first getMap() / getText(), which puts a new object in
+    // doc.share under the same name (the size doesn't change)
+    let names = new Map();
+    const nameOf = (t) => {
+        let n = names.get(t);
+        if (n === undefined) {
+            names = new Map([...doc.share].map(([k, v]) => [v, k]));
+            n = names.get(t);
+        }
+        return n;
+    };
+    // what a transaction changed (mapping.ts Dirty)
+    const dirtyOf = (tr) => {
+        const types = new Set(), roots = new Set();
+        for (const t of tr.changed.keys()) {
+            let r = t;
+            types.add(r);
+            while (r._item) {
+                r = r._item.parent;
+                types.add(r);
+            }
+            const n = nameOf(r);
+            if (n)
+                roots.add(n);
+        }
+        return { types, roots, changed: tr.changed };
+    };
+    const touches = (d, k) => {
+        for (const n of d.roots)
+            if (n === k || n.startsWith(k + '.'))
+                return true;
+        return false;
+    };
+    const onTransaction = (tr) => {
+        if (!slices.size || !tr.changed.size)
+            return;
+        const d = dirtyOf(tr);
+        for (const s of slices.values()) {
+            if (!s.started || !touches(d, s.key))
+                continue;
+            s.mirror = read(s.y, s.key, s.mirror, d);
+            if (tr.origin !== local && tr.origin !== seed)
+                emit(s, !!s.um && tr.origin === s.um);
+        }
+    };
+    doc.on('afterTransaction', onTransaction);
+    const slice = (k) => {
+        let s = slices.get(k);
+        if (s)
+            return s;
+        s = { key: k, y: doc.getMap(k), started: false, first: undefined, last: undefined, mirror: undefined, emitted: new Set(), sent: undefined, sentBase: undefined, seed: 'whenSynced', out: new Set() };
+        if (o.undo !== false)
+            s.um = new Y__namespace.UndoManager(s.y, { trackedOrigins: new Set([local]), captureTimeout: o.captureTimeout ?? 500 });
+        slices.set(k, s);
+        return s;
+    };
+    // the slice's path-named root types join its undo scope inside the transaction that may create them
+    const scope = (s) => {
+        if (s.um)
+            for (const [n, t] of doc.share)
+                if (n.startsWith(s.key + '.'))
+                    s.um.addToScope(t);
+    };
+    const write = (s, prev, next, origin) => doc.transact(() => { writeMap(s.y, prev, next, opts, s.key, s.shape); scope(s); }, origin);
+    // the document's content as a REMOTE action, unless the app already has it (or has it on its way)
+    const emit = (s, undo = false) => {
+        // the mirror takes the app's objects wherever they are equal (Collection items keep their identity)
+        if (s.mirror !== s.sent)
+            s.mirror = reconcile(s.last, s.mirror);
+        const value = s.mirror;
+        if (value === s.last || value === s.sent && s.sentBase === s.last)
+            return;
+        s.sent = value;
+        s.sentBase = s.last;
+        s.emitted.add(value);
+        for (const l of s.out)
+            l.next(undo ? { value, base: s.last, undo } : { value, base: s.last });
+    };
+    // bind the slice to the document: seed an empty one from the app's value, or else take its
+    // content (with the app's edits since its first value written onto it)
+    const start = (s) => {
+        s.started = true;
+        const v = s.last;
+        if (s.y.size == 0)
+            write(s, {}, v, seed);
+        else if (v !== s.first)
+            write(s, s.first, v, local);
+        s.mirror = read(s.y, s.key);
+        emit(s);
+    };
+    /*
+     * state[key]'s value: from `key.LOCAL` (coalesced per flush) and from every `key.REMOTE` (its
+     * driver sink sends the state the REMOTE reducer committed: the REMOTE value when it applied,
+     * else the app's own newer value). So the driver always diffs from a value the app really had.
+     */
+    const onLocal = (c) => {
+        onValue(c);
+        // history() (sygnal/canvas): one undo step per commit, however long the gesture took
+        if (c.step === undefined)
+            return;
+        const s = slice(c.key);
+        if (s.um)
+            s.um.captureTimeout = Infinity;
+        if (c.step !== s.step) {
+            if (s.step !== undefined)
+                s.um?.stopCapturing();
+            s.step = c.step;
+        }
+    };
+    const onValue = (c) => {
+        const s = slice(c.key), v = c.value;
+        if (v === undefined)
+            return;
+        if (!s.started) {
+            if (s.first === undefined) {
+                s.first = v;
+                s.shape = normShape(c.shape);
+                s.seed = c.seed || 'whenSynced';
+            }
+            s.last = v;
+            if (synced || s.seed == 'ifEmpty')
+                start(s);
+            return;
+        }
+        // the app took a REMOTE value (or nothing changed): any newer document content follows
+        if (v === s.last || s.emitted.has(v)) {
+            // REMOTE actions run in order: the ones sent before this one were answered already
+            if (v !== s.last)
+                for (const e of s.emitted) {
+                    s.emitted.delete(e);
+                    if (e === v)
+                        break;
+                }
+            s.last = v;
+            return emit(s);
+        }
+        write(s, s.last, v, local);
+        s.last = v;
+        s.emitted.clear();
+        emit(s);
+    };
+    sink$.addListener({
+        next: (c) => {
+            if (!c)
+                return;
+            if ('value' in c && c.key)
+                onLocal(c);
+            if (c.undo)
+                slice(c.undo).um?.undo();
+            if (c.redo)
+                slice(c.redo).um?.redo();
+            if (c.presence && awareness)
+                awareness.setLocalState({ ...awareness.getLocalState(), ...c.presence });
+            if (typeof c.connect == 'boolean')
+                c.connect ? provider?.connect?.() : provider?.disconnect?.();
+        },
+        error: () => { },
+        complete: () => {
+            doc.off('afterTransaction', onTransaction);
+            for (const s of slices.values())
+                s.um?.destroy();
+        },
+    });
+    const others = () => [...awareness.getStates()].filter(([id]) => id !== awareness.clientID).map(([id, st]) => ({ id, ...st }));
+    return {
+        /** remote content for state[key], as { value, base } */
+        remote: (k) => {
+            let l;
+            return sygnal.xs.create({ start: (x) => { slice(k).out.add(l = x); }, stop: () => { slice(k).out.delete(l); } });
+        },
+        /** the other clients' presence states, on every awareness change */
+        presence: () => {
+            if (!awareness)
+                return sygnal.xs.empty();
+            let f;
+            return sygnal.xs.create({
+                start: (l) => { f = () => l.next(others()); f(); awareness.on('change', f); },
+                stop: () => { awareness.off('change', f); },
+            });
+        },
+        /** { canUndo, canRedo } for state[key]'s per-user history */
+        history: (k) => {
+            let f;
+            const um = () => slice(k).um, ev = ['stack-item-added', 'stack-item-popped', 'stack-cleared'];
+            return sygnal.xs.create({
+                start: (l) => {
+                    const u = um();
+                    f = () => l.next({ canUndo: !!u?.canUndo(), canRedo: !!u?.canRedo() });
+                    f();
+                    for (const e of ev)
+                        u?.on(e, f);
+                },
+                stop: () => { for (const e of ev)
+                    um()?.off(e, f); },
+            });
+        },
+        doc,
+    };
+};
+
+/*
+ * 'sygnal/yjs' (research: dev-plans/research/crdt-state): shared(), the behavior that binds one
+ * top-level state key to the Yjs driver's document.
+ *
+ *   Board.uses = { board: shared({ presence: 'peers', history: 'history' }) }   // state.board is shared
+ *   Board.model = {
+ *     ADD:  (state, item) => ({ ...state, board: { ...state.board, items: [...state.board.items, item] } }),
+ *     UNDO: { SHARED: { undo: 'board' } },                      // this user's changes only
+ *     HERE: { SHARED: (_, id) => ({ presence: { editing: id } }) },
+ *   }
+ *
+ * The model stays the only writer of state:
+ * - `board.LOCAL`: every new value of state.board reaches the driver as data, once per flush (the
+ *   values of one flush coalesce: a burst of actions is one Yjs transaction).
+ * - `board.REMOTE` ({ value, base }): a document change from elsewhere; it applies only while
+ *   state.board is still `base` (no unsynced local edit is overwritten), and its driver sink tells
+ *   the driver the state it committed either way.
+ * - `board.PRESENCE` / `board.HISTORY` with `presence: 'peers'` / `history: 'history'`: the other
+ *   clients' awareness states and { canUndo, canRedo } in those state keys.
+ * LOCAL and REMOTE are marked as built-in actions (`Symbol.for('sygnal.builtIn')` on their
+ * handlers): the action log calls them 'built-in', so DevTools hides them with INITIALIZE (Q5).
+ *
+ * `ownsState: false`: the host's initialState keeps state[key] (the first value seeds an empty
+ * document); the behavior adds no slice of its own, and sygnal-check's SYG127 reads the marker.
+ * `undo()` on the same key reverts other users' changes: SYG260 (dev) points to `{ SHARED: { undo } }`.
+ *
+ * sygnal/canvas's `history(key)` routes here (maintainer decision 7, one API): model entries that
+ * are its `undo` / `redo` become `{ [driver]: { undo: key } }` / `{ redo: key }`, its `commit`
+ * bumps `state[step]` instead of keeping snapshots, and the LOCAL command carries that step, so the
+ * driver closes this user's undo step at each commit (one step per gesture). `after` runs on the
+ * state an undo / redo brings back. The marker is `Symbol.for('sygnal.history')`: no import.
+ */
+const BUILT_IN = Symbol.for('sygnal.builtIn');
+const HISTORY = Symbol.for('sygnal.history');
+const builtIn = (f) => (f[BUILT_IN] = true, f);
+// SYG260: an undo() behavior of the host whose `key` is this shared key (reported once per use)
+const reported = new WeakSet();
+const checkUndo = (c, k) => {
+    const d = globalThis.__SYGNAL_DIAGNOSTICS__, u = c.view?.uses;
+    if (!d || !u)
+        return;
+    for (const n in u) {
+        const b = u[n], key = b?.options?.key;
+        if (!b?.model?.UNDO || !b.model.REDO || !(key === k || Array.isArray(key) && key.includes(k)) || reported.has(b))
+            continue;
+        reported.add(b);
+        try {
+            d.report('SYG260', {
+                severity: 'warn', component: c, data: { key: k, uses: n },
+                message: `undo() (uses key '${n}') records '${k}', which shared() syncs: its UNDO restores a snapshot of the whole slice and reverts other users' changes made since`,
+                fix: `Remove undo() for '${k}' and use the driver's per-user undo: UNDO: { SHARED: { undo: '${k}' } }, REDO: { SHARED: { redo: '${k}' } }, with shared({ history: 'history' }) for canUndo / canRedo`,
+            });
+        }
+        catch (e) {
+            queueMicrotask(() => { throw e; });
+        }
+    }
+};
+/** `uses = { [key]: shared(options) }`: state[key] lives in the Yjs driver's document */
+const shared = (opts = {}) => ({
+    options: opts,
+    ownsState: false,
+    merge(c, k) {
+        const D = opts.driver || 'SHARED', S = c.stateSourceName || 'STATE', model = c.model = { ...c.model };
+        const { shape, seed } = opts;
+        checkUndo(c, k);
+        // sygnal/canvas history(k): its undo / redo entries go to this user's UndoManager
+        let hist = null;
+        for (const name in model) {
+            const e = model[name], f = typeof e == 'function' ? e : e?.[S], h = f?.[HISTORY];
+            if (!h || h.field !== k)
+                continue;
+            hist = h;
+            const cmd = f === h.undo ? { undo: k } : { redo: k }, rest = typeof e == 'function' ? {} : { ...e };
+            delete rest[S];
+            model[name] = { ...rest, [D]: () => cmd };
+        }
+        if (hist)
+            hist.shared = { history: opts.history };
+        const step = hist?.step;
+        // the committed slice when the action runs (not the action's data: a REMOTE queued before it may have moved it on)
+        model[k + '.LOCAL'] = { [D]: builtIn((s) => step ? { key: k, value: s?.[k], shape, seed, step: s?.[step] ?? 0 } : { key: k, value: s?.[k], shape, seed }) };
+        model[k + '.REMOTE'] = {
+            [S]: builtIn((s, d) => s?.[k] !== d.base ? sygnal.ABORT : d.undo && hist ? hist.after({ ...s, [k]: d.value }) : { ...s, [k]: d.value }),
+            // the state the REMOTE committed (its value, or the app's own newer one) is the driver's new base
+            [D]: builtIn((s) => ({ key: k, value: s?.[k] })),
+        };
+        if (opts.presence)
+            model[k + '.PRESENCE'] = { [S]: (s, peers) => ({ ...s, [opts.presence]: peers }) };
+        if (opts.history)
+            model[k + '.HISTORY'] = { [S]: (s, h) => ({ ...s, [opts.history]: h }) };
+        const own = c.intent, owned = c._behaviorActions || (c._behaviorActions = {});
+        for (const a of ['LOCAL', 'REMOTE', 'PRESENCE', 'HISTORY'])
+            owned[k + '.' + a] = k;
+        c.intent = (so) => {
+            // no Yjs driver (renderComponent without one: a fake source): the reducers still run
+            const h = own?.(so) || {}, st = so[S], src = typeof so[D]?.remote == 'function' ? so[D] : null;
+            // state[key]'s latest value once per flush (a microtask after the first change of a burst)
+            let prev, latest, queued = false, sub, prevStep, latestStep;
+            const local$ = sygnal.xs.create({
+                start: (l) => {
+                    sub = st.stream.subscribe({
+                        next: (s) => {
+                            latest = s?.[k];
+                            if (step)
+                                latestStep = s?.[step];
+                            if (queued)
+                                return;
+                            queued = true;
+                            queueMicrotask(() => {
+                                queued = false;
+                                if (sub && latest !== undefined && (latest !== prev || latestStep !== prevStep))
+                                    prevStep = latestStep, l.next(prev = latest);
+                            });
+                        },
+                        error: () => { }, complete: () => { },
+                    });
+                },
+                stop: () => { sub?.unsubscribe(); sub = undefined; },
+            });
+            const o = {
+                [k + '.LOCAL']: local$,
+                [k + '.REMOTE']: src ? src.remote(k) : sygnal.xs.never(),
+                ...(opts.presence && { [k + '.PRESENCE']: src ? src.presence() : sygnal.xs.never() }),
+                ...(opts.history && { [k + '.HISTORY']: src ? src.history(k) : sygnal.xs.never() }),
+                // the host's own actions (and renderComponent's simulateAction streams) win
+                ...h,
+            };
+            // renderComponent's marker (non-enumerable) for a behavior merged after this one
+            if (h.__sygnalTestActions)
+                Object.defineProperty(o, '__sygnalTestActions', { value: h.__sygnalTestActions });
+            return o;
+        };
+    },
+});
+
+exports.collection = collection;
+exports.makeYjsDriver = makeYjsDriver;
+exports.shared = shared;
+//# sourceMappingURL=yjs.cjs.js.map