@panphora/clayjs 1.15.2 → 1.16.0

package/src/page/ybind/awareness.js

@@ -0,0 +1,172 @@
+// A selection as a peer can name it, and a peer's target read back in this tab's
+// document: stable block ids, guarded Yjs relative positions, and the winning
+// copy's coordinates. Nothing here is stored or saved; a target is built from the
+// current document and thrown away.
+import * as Y from "../../vendor/yjs.vendor.js";
+import { toBase64, fromBase64 } from "../../vendor/yjs.vendor.js";
+import { state as pmState } from "../../vendor/prosemirror.vendor.js";
+import { yBefore, yAfter } from "./tokens.js";
+import { posAtY, yIndexAt, cellPoint, cellRange } from "./positions.js";
+import { BlockSelection } from "../blocks.js";
+
+// A block selection publishes its ids, bounded so one person can never make a
+// target too large for the host to accept.
+export const MAX_BLOCK_IDS = 128;
+
+const blockIdOf = ($pos) => ($pos.depth ? $pos.node(1).attrs.id : null);
+const inTable = ($pos) => !!$pos.depth && $pos.node(1).type.name === "table";
+
+const relativeTo = (pd, doc, w, pos, assoc) =>
+  toBase64(Y.encodeRelativePosition(Y.createRelativePositionFromTypeIndex(pd.flow, yIndexAt(doc, w.holes, pos, w.visible), assoc)));
+
+/**
+ * One selection as a peer publishes it, or null when it has no page coordinates
+ * (a mixed selection, a caret with no block, a table range across cells).
+ */
+export function encodeSelection({ pd, w, doc }, selection) {
+  if (!pd || !w || !doc || !selection) return null;
+  if (selection instanceof pmState.TextSelection) {
+    const $anchor = selection.$anchor, $head = selection.$head;
+    if (inTable($anchor) || inTable($head)) {
+      const anchor = cellPoint(doc, $anchor.pos), head = cellPoint(doc, $head.pos);
+      if (!anchor || !head || anchor.table !== head.table || anchor.row !== head.row || anchor.col !== head.col) return null;
+      return { kind: "cell", block: anchor.table, row: anchor.row, col: anchor.col };
+    }
+    const from = Math.min(selection.from, selection.to);
+    const end = ($pos) => {
+      const block = blockIdOf($pos);
+      if (block === null) return null;
+      return { block, rel: relativeTo(pd, doc, w, $pos.pos, selection.empty || $pos.pos === from ? 0 : -1) };
+    };
+    const anchor = end($anchor), head = end($head);
+    return anchor && head ? { kind: "text", anchor, head } : null;
+  }
+  if (selection instanceof BlockSelection || selection instanceof pmState.NodeSelection) {
+    const ids = [];
+    if (selection instanceof BlockSelection) {
+      const { lo, hi } = selection.span();
+      doc.forEach((node, _at, index) => { if (index >= lo && index <= hi) ids.push(node.attrs.id); });
+    } else {
+      const node = doc.nodeAt(selection.from);
+      if (node) ids.push(node.attrs.id);
+    }
+    if (!ids.length) return null;
+    if (ids.length > MAX_BLOCK_IDS) {
+      const focused = blockIdOf(selection.$from);
+      return focused ? { kind: "blocks", ids: [focused] } : null;
+    }
+    return { kind: "blocks", ids };
+  }
+  return null;
+}
+
+const indexOf = (pd, end) => {
+  if (!end || typeof end !== "object" || typeof end.block !== "string" || !end.block || typeof end.rel !== "string" || !end.rel) return null;
+  let rel;
+  try { rel = Y.decodeRelativePosition(fromBase64(end.rel)); } catch { return null; }
+  let abs;
+  try { abs = Y.createAbsolutePositionFromRelativePosition(rel, pd.ydoc); } catch { return null; }
+  // A position that names another shared type is not this document's: the peer
+  // wrote against a document this tab does not hold.
+  if (!abs || abs.type !== pd.flow) return null;
+  return abs.index;
+};
+
+// Whether the flow still holds text at that index: a join keeps it, a deletion
+// and an undone Restore do not.
+const aliveAt = (pd, index) => {
+  let at = 0;
+  for (let it = pd.flow._start; it; it = it.right) {
+    const end = at + it.length;
+    if (index < end) return !it.deleted;
+    at = end;
+  }
+  return false;
+};
+
+const liveMarker = (pd, id) => {
+  for (let it = pd.flow._start; it; it = it.right) if (!it.deleted && it.content instanceof Y.ContentEmbed && it.content.embed?.b === id) return true;
+  return false;
+};
+
+// Where a flow index sits inside its own block, read from the flow itself: the
+// marker the index follows and how far into that block's text it is. A moved
+// block leaves its old text behind as a hidden copy, so the index still names the
+// block that was moved and the offset the person had.
+const offsetInBlock = (pd, index) => {
+  let at = 0, id = null, start = 0;
+  for (let it = pd.flow._start; it; it = it.right) {
+    if (it.content instanceof Y.ContentEmbed && it.content.embed?.b !== undefined) {
+      id = it.content.embed.b;
+      start = at + it.length;
+    }
+    at += it.length;
+    if (at > index && id !== null) return { id, offset: index - start };
+  }
+  return id === null ? null : { id, offset: index - start };
+};
+
+const placeInBlock = (doc, id, offset) => {
+  let found = null;
+  doc.forEach((node, pos) => { if (found === null && node.attrs.id === id && node.isTextblock) found = pos + 1 + Math.min(Math.max(offset, 0), node.content.size); });
+  return found;
+};
+
+// A failed resolution is null, never a neighbouring block: the caller hides it
+// instead of drawing it somewhere plausible. A block that moved is the same
+// logical block at a new place, so it is placed by its id and the offset the
+// person had; a block that is hidden or gone has no place here at all.
+const placeEnd = ({ pd, w, doc }, end) => {
+  const index = indexOf(pd, end);
+  if (index === null) return null;
+  const pos = posAtY(doc, w.holes, w.tokens, index, w.visible);
+  if (blockIdOf(doc.resolve(pos)) === end.block) return pos;
+  const spot = offsetInBlock(pd, index);
+  if (spot && spot.id === end.block) {
+    const moved = placeInBlock(doc, end.block, spot.offset);
+    if (moved !== null) return moved;
+  }
+  // A block that still exists in the flow but not in the document is hidden, and a
+  // position that landed elsewhere is not this caret's. A block the peer named that
+  // no longer exists anywhere was joined into the one that now holds its text, and
+  // the relative position says where in it.
+  if (liveMarker(pd, end.block) || !aliveAt(pd, index)) return null;
+  // A position inside a hole is text this tab does not show; only a position in
+  // visible text may stand in for a block that was joined away.
+  if (w.holes.some((hole) => index >= yBefore(w.holes, hole.at) && index < yAfter(w.holes, hole.at))) return null;
+  return doc.resolve(pos).parent.inlineContent ? pos : null;
+};
+
+/**
+ * A published selection read back in this tab's current document: page
+ * positions, or null when any part of it no longer names this document's text.
+ * A hidden block, a deleted one, a position from another document or bytes that
+ * do not decode are all nulls, and a null is a caret that is not drawn.
+ */
+export function decodeSelection({ pd, w, doc }, selection) {
+  if (!pd || !w || !doc || !selection || typeof selection !== "object") return null;
+  if (selection.kind === "text") {
+    const anchor = placeEnd({ pd, w, doc }, selection.anchor);
+    const head = placeEnd({ pd, w, doc }, selection.head);
+    if (anchor === null || head === null) return null;
+    return { kind: "text", from: Math.min(anchor, head), to: Math.max(anchor, head) };
+  }
+  if (selection.kind === "cell") {
+    const cell = cellRange(doc, { table: selection.block, row: selection.row, col: selection.col, offset: 0 });
+    if (!cell) return null;
+    return { kind: "cell", from: cell.from, to: cell.to, block: cell.block, row: cell.row, col: cell.col };
+  }
+  if (selection.kind === "blocks") {
+    const ids = [];
+    const ranges = [];
+    for (const id of Array.isArray(selection.ids) ? selection.ids : []) {
+      doc.forEach((node, at) => {
+        if (node.attrs.id !== id || ids.includes(id)) return;
+        ids.push(id);
+        ranges.push({ from: at, to: at + node.nodeSize });
+      });
+    }
+    return ranges.length ? { kind: "blocks", ids, ranges } : null;
+  }
+  return null;
+}

package/src/page/ybind/binding.js

@@ -63,8 +63,16 @@ export function createYPageBinding({ store, ydoc = new Y.Doc(), onNotice = () =>
     });
   }
 
+  // What the page's awareness UI asks of the mapping: the document, and the bridge's
+  // current walk, which is the winning-copy view a remote position is read in and a
+  // local one is written from. The UI never reaches into the bridge itself.
+  const awareness = {
+    generation: () => (Number.isSafeInteger(store.value?.g) && store.value.g >= 0 ? store.value.g : 0),
+    map: () => ({ pd, w: bridge.walk }),
+  };
+
   return {
-    ydoc, pd, provider, bridge, stats, flush,
+    ydoc, pd, provider, bridge, stats, flush, awareness,
     doc: () => keepViewPos(docOf(pd, walk(pd))),
     attach: (view) => bridge.attach(view),
     dispatch: (tr) => bridge.dispatch(tr),

package/src/page/ybind/bridge.js

@@ -3,31 +3,17 @@ import { REMOTE_META, LOCAL, HISTORY_META, attrKeys, sameJson, parseKey, mintOp
 import { walk, hashText } from "./walk.js";
 import { docOf } from "./doc.js";
 import { localGroup } from "./group.js";
-import { tokenIndex, yBefore, yAfter } from "./tokens.js";
+import { yBefore, yAfter } from "./tokens.js";
+import { yIndexAt, posAtY, cellPoint, cellAt } from "./positions.js";
 import { state as pmState } from "../../vendor/prosemirror.vendor.js";
 import { repairSiblings } from "../model.js";
 import { createOriginIndex, installUndoOrigins } from "./origins.js";
 import { reduceRecovery, canonicalRevision, restoreKey, physicalKeyOf, authorKey, RECOVERED_PREFIX, parsePhysicalKey, parseGoneIntents } from "./recovery.js";
 import { moveBlocks } from "./moves.js";
 import { createBoardCommands } from "./board-commands.js";
+import { continuesGroup, intentOf } from "../history-intent.js";
 import { MOVE, BlockSelection } from "../blocks.js";
 
-const yIndexAt = (doc, holes, pos, visible) => yBefore(holes, tokenIndex(doc, new Map(), visible)[pos]);
-
-export function posAtY(doc, holes, tokens, y, visible = null) {
-  let lo = 0, hi = tokens;
-  while (lo < hi) { const mid = (lo + hi + 1) >> 1; if (yBefore(holes, mid) <= y) lo = mid; else hi = mid - 1; }
-  const idx = tokenIndex(doc, new Map(), visible);
-  let first = -1;
-  for (let p = 0; p < idx.length; p++) {
-    if (idx[p] < lo) continue;
-    if (idx[p] > lo) break;
-    if (first < 0) first = p;
-    if (doc.resolve(p).parent.inlineContent) return p;
-  }
-  return first < 0 ? doc.content.size : first;
-}
-
 export const shapeOf = (doc) => { const out = []; doc.forEach((b) => out.push([b.type.name, b.attrs.id, JSON.stringify(Object.fromEntries(attrKeys(b.type).map((k) => [k, b.attrs[k]]))), b.isTextblock || b.type.name === "table" ? JSON.stringify(b.content.toJSON()) : null])); return JSON.stringify(out); };
 export const bareShape = (doc) => { const out = []; doc.forEach((b) => out.push([b.type.name, JSON.stringify(Object.fromEntries(attrKeys(b.type).map((k) => [k, b.attrs[k]]))), b.isTextblock || b.type.name === "table" ? JSON.stringify(b.content.toJSON()) : null])); return JSON.stringify(out); };
 export function sameBareShape(a, b) {
@@ -41,6 +27,22 @@ export function sameBareShape(a, b) {
   return true;
 }
 
+const opaqueRanges = (doc) => {
+  const out = [];
+  doc.forEach((node, pos) => { if (node.type.name === "opaque_block") out.push([pos, pos + node.nodeSize]); });
+  return out;
+};
+
+// A command that would rewrite an opaque block, or cut through it, is refused
+// before the view or the document changes. A command that merely touches its
+// neighbours keeps working.
+const touchesOpaque = (step, ranges) => {
+  const from = typeof step.from === "number" ? step.from : typeof step.pos === "number" ? step.pos : null;
+  if (from === null) return false;
+  const to = typeof step.to === "number" ? step.to : from + 1;
+  return ranges.some(([start, end]) => from < end && to > start);
+};
+
 const tableSpan = (doc, pos) => {
   const $pos = doc.resolve(pos);
   return $pos.depth && $pos.node(1).type.name === "table" ? [$pos.before(1), $pos.after(1)] : null;
@@ -62,27 +64,6 @@ export function docDiff(oldDoc, newDoc) {
   return { start, endA, endB };
 }
 
-const cellPoint = (doc, pos) => {
-  const $pos = doc.resolve(pos);
-  if ($pos.depth !== 3 || $pos.parent.type.name !== "table_cell") return null;
-  return { table: $pos.node(1).attrs.id, row: $pos.node(2).attrs.id, col: $pos.parent.attrs.col, offset: $pos.parentOffset };
-};
-
-const cellAt = (doc, point) => {
-  let found = null;
-  doc.forEach((table, at) => {
-    if (found !== null || table.type.name !== "table" || table.attrs.id !== point.table) return;
-    table.forEach((row, rowAt) => {
-      if (found !== null || row.attrs.id !== point.row) return;
-      row.forEach((cell, cellAt) => {
-        if (found === null && cell.attrs.col === point.col) found = at + 2 + rowAt + cellAt + 1 + Math.min(point.offset, cell.content.size);
-      });
-    });
-  });
-  return found;
-};
-
-
 export function keepViewPos(derived, current = null) {
   const previous = new Map();
   current?.forEach((block) => { if (block.attrs.id) previous.set(block.attrs.id, block); });
@@ -207,6 +188,9 @@ export function createBridge({ pd, onNotice = () => {}, ownedTokens = [], author
     return docOf(pd, w);
   };
   let saved = null;
+  let lastIntent = null;
+  let groupOpen = false;
+  let joining = false;
   const render = (own = false, fresh = null) => {
     stats.renders++;
     const keep = saved;
@@ -244,6 +228,7 @@ export function createBridge({ pd, onNotice = () => {}, ownedTokens = [], author
     view.dispatch(tr);
   };
   const onBefore = (t) => {
+    if (groupOpen && !joining && t.origin === LOCAL) { um.stopCapturing(); groupOpen = false; }
     if (!view || t.origin === LOCAL || t.origin === um || saved) return;
     const sel = view.state.selection;
     if (!(sel instanceof pmState.TextSelection)) return;
@@ -259,18 +244,19 @@ export function createBridge({ pd, onNotice = () => {}, ownedTokens = [], author
     saved = { anchor: end(sel.$anchor), head: end(sel.$head) };
   };
   const onAfter = (t) => {
+    if (t.origin !== LOCAL) { lastIntent = null; groupOpen = false; }
     if (!view) { bumpRecovery(); return; }
     if (t.origin === LOCAL) { saved = null; return; }
     render(t.origin === um);
   };
   const portMove = (tr, move) => {
     const result = moveBlocks({ pd, view, um, origins, render }, move);
-    if (result.status === "refused") {
-      stats.moveFallbacks = (stats.moveFallbacks ?? 0) + 1;
-      return false;
+    if (result.status !== "moved") {
+      if (result.status === "refused") stats.moveRefusals = (stats.moveRefusals ?? 0) + 1;
+      return result;
     }
     const sel = tr.selection;
-    if (sel instanceof pmState.TextSelection) return true;
+    if (sel instanceof pmState.TextSelection) return result;
     const doc = view.state.doc;
     let from = null, to = null;
     doc.forEach((node, pos) => {
@@ -278,13 +264,13 @@ export function createBridge({ pd, onNotice = () => {}, ownedTokens = [], author
       if (from === null) from = pos;
       to = pos + node.nodeSize;
     });
-    if (from === null) return true;
+    if (from === null) return result;
     const next = sel instanceof pmState.NodeSelection
       ? pmState.NodeSelection.create(doc, from)
       : sel.anchor <= sel.head ? new BlockSelection(doc.resolve(from), doc.resolve(to)) : new BlockSelection(doc.resolve(to), doc.resolve(from));
     const reselect = view.state.tr.setSelection(next).setMeta(REMOTE_META, true).setMeta("addToHistory", false);
     view.dispatch(tr.scrolledIntoView ? reselect.scrollIntoView() : reselect);
-    return true;
+    return result;
   };
   const board = createBoardCommands({ pd, um, origins, render: () => (view ? render() : refresh()) });
   pd.ydoc.on("beforeTransaction", onBefore);
@@ -321,16 +307,33 @@ export function createBridge({ pd, onNotice = () => {}, ownedTokens = [], author
     },
     dispatch(tr) {
       const move = tr.getMeta(MOVE);
-      if (move && portMove(tr, move)) return;
+      if (move) return portMove(tr, move);
+      const ranges = opaqueRanges(view.state.doc);
+      if (ranges.length && tr.steps.some((step) => touchesOpaque(step, ranges))) return { status: "refused", code: "unsupported-format" };
       const { state, transactions } = view.state.applyTransaction(tr);
       const local = transactions.filter((t) => t.docChanged && !t.getMeta(REMOTE_META));
       view.updateState(state);
-      if (!local.length) return;
+      if (!local.length) {
+        if (transactions.some((t) => t.selectionSet && !t.getMeta(REMOTE_META))) {
+          lastIntent = null;
+          if (groupOpen) { um.stopCapturing(); groupOpen = false; }
+        }
+        return;
+      }
       w = walk(pd);
       const history = transactions.every((t) => t.getMeta("addToHistory") !== false);
       const register = registerAuthor;
       registerAuthor = null;
-      localGroup(pd, local, w, stats, um, history, register);
+      const intent = history ? intentOf(local, view) : null;
+      const join = groupOpen && continuesGroup(lastIntent, intent);
+      lastIntent = intent;
+      joining = join;
+      try {
+        localGroup(pd, local, w, stats, um, history, register, { join, open: intent !== null });
+      } finally {
+        joining = false;
+      }
+      groupOpen = intent !== null;
       const derived = refresh();
       if (!sameBareShape(derived, view.state.doc)) {
         stats.mismatch++;

package/src/page/ybind/decode.js

@@ -6,6 +6,7 @@ import { createPageDoc, attrKeys, defaultOf, sameJson, PAGE_ROOTS } from "./layo
 import { resolveBoardFields } from "./board.js";
 import { resolveTableFields } from "./table.js";
 import { markName } from "./marks.js";
+import { entriesOfYjs } from "../format-codec.js";
 import { walk } from "./walk.js";
 import { docFromValue, YDecodeError } from "./provider.js";
 import { parseGoneIntents, parsePhysicalKey, RecoveryError } from "./recovery.js";
@@ -25,6 +26,13 @@ const isPlain = (value) => value !== null && typeof value === "object" && !Array
 const originId = (client, clock) => `${client}.${clock}`;
 const boundaryIdentity = (record) => JSON.stringify([record.blockId, record.kind, record.recoveryOf ?? null]);
 
+// A mark name this runtime has no schema for is kept when the codec reads it as a
+// valid descriptor, a named mark or the reserved compact-token bridge, and refused
+// when it is malformed.
+const keptMark = (key, value) => {
+  try { entriesOfYjs({ [markName(key)]: value }); return true; } catch { return false; }
+};
+
 function validateFlow(pd) {
   if (pd.flow._map.size) unsupported("The page flow must contain text and block markers");
   for (let it = pd.flow._start; it; it = it.right) {
@@ -32,7 +40,7 @@ function validateFlow(pd) {
     const c = it.content;
     if (c instanceof Y.ContentString) continue;
     if (c instanceof Y.ContentFormat) {
-      if (c.value !== null && !Object.hasOwn(schema.marks, markName(c.key))) unsupported(`Unsupported page mark: ${c.key}`);
+      if (c.value !== null && !Object.hasOwn(schema.marks, markName(c.key)) && !keptMark(c.key, c.value)) unsupported(`Unsupported page mark: ${c.key}`);
       continue;
     }
     if (c instanceof Y.ContentEmbed) {
@@ -132,8 +140,45 @@ function validateOrigins(pd) {
   }
 }
 
+// The text a block's runs carry, as one record states it: characters and the mark
+// key of each, a hard break as an atom.
+function textOf(block) {
+  let text = "";
+  const units = [];
+  for (const run of block.runs) {
+    if (run.hole) continue;
+    if (run.br) {
+      if (block.t === "code_block") unsupported("A code block cannot contain a hard-break atom");
+      text += ATOM;
+      units.push(BREAK);
+    } else {
+      text += run.text;
+      const key = markKey([...run.marks].sort((a, b) => a.type.rank - b.type.rank));
+      for (let i = 0; i < run.text.length; i++) units.push(key);
+    }
+  }
+  const out = { c: text };
+  if (units.some(Boolean)) out.m = runsOf(units);
+  return out;
+}
+
+// The attributes a block's Y attribute map, or a recovered root, states for it.
+const attributeFields = (block, attrs) => (block.fields ? Object.entries(block.fields) : attrs ? attrs.entries() : []);
+
+// A block type this runtime has no schema for keeps the record it stands for: its
+// own type, its text and marks and every attribute a newer peer wrote on it.
+function opaqueBlockOf(pd, block, index) {
+  const attrs = pd.attrs.get(block.baseId);
+  const out = { t: block.t, pos: String(index + 1).padStart(8, "0") };
+  for (const [key, value] of attributeFields(block, attrs)) if (key !== "t" && key !== "pos") out[key] = copy(value);
+  return Object.assign(out, textOf(block));
+}
+
 function blockOf(pd, block, index) {
-  if (!Object.hasOwn(DEFAULTS, block.t)) unsupported(`Unsupported page block type: ${block.t}`);
+  if (!Object.hasOwn(DEFAULTS, block.t)) {
+    if (typeof block.t !== "string" || !block.t || block.t === "opaque_block") unsupported(`Unsupported page block type: ${block.t}`);
+    return opaqueBlockOf(pd, block, index);
+  }
   const type = schema.nodes[block.t];
   const attrs = pd.attrs.get(block.baseId);
   const table = block.t === "table" && !block.fields ? resolveTableFields(pd.tableFields, block.baseId, { cols: attrs?.get("cols"), rows: attrs?.get("rows") }) : null;
@@ -145,24 +190,12 @@ function blockOf(pd, block, index) {
   }
   if (block.t === "table") out.rows = copy((block.fields ? block.fields.rows : table.rows) ?? {});
   if (block.t === "board") Object.assign(out, block.fields ? { columns: copy(block.fields.columns ?? {}), cards: copy(block.fields.cards ?? {}) } : resolveBoardFields(pd.boardFields, block.baseId));
-  if (type.isTextblock) {
-    let text = "";
-    const units = [];
-    for (const run of block.runs) {
-      if (run.hole) continue;
-      if (run.br) {
-        if (block.t === "code_block") unsupported("A code block cannot contain a hard-break atom");
-        text += ATOM;
-        units.push(BREAK);
-      } else {
-        text += run.text;
-        const key = markKey([...run.marks].sort((a, b) => a.type.rank - b.type.rank));
-        for (let i = 0; i < run.text.length; i++) units.push(key);
-      }
-    }
-    out.c = text;
-    if (units.some(Boolean)) out.m = runsOf(units);
+  const known = new Set(attrKeys(type));
+  for (const [key, value] of attributeFields(block, attrs)) {
+    if (key === "t" || key === "pos" || known.has(key) || Object.hasOwn(out, key)) continue;
+    out[key] = copy(value);
   }
+  if (type.isTextblock) Object.assign(out, textOf(block));
   return out;
 }
 

package/src/page/ybind/doc.js

@@ -14,8 +14,24 @@ export const fieldsOf = (pd, b, type) => {
   return out;
 };
 
+const copy = (value) => (value === undefined ? value : JSON.parse(JSON.stringify(value)));
+
+// Every attribute a block record holds, known or not, without the structural
+// position: the record an opaque block keeps and writes back unchanged.
+const rawOf = (pd, b) => {
+  const out = {};
+  const m = pd.attrs.get(b.baseId);
+  if (m) m.forEach((value, key) => { if (key !== "pos") out[key] = copy(value); });
+  out.t = b.t;
+  return out;
+};
+
 export function docOf(pd, w) {
   const blocks = w.visible.map((b) => {
+    if (b.opaque) {
+      const fields = b.recovered ? { ...copy(b.fields ?? {}) } : rawOf(pd, b);
+      return { b, type: schema.nodes.opaque_block, fields, opaque: true };
+    }
     const type = schema.nodes[b.t] ?? schema.nodes.paragraph;
     return { b, type, fields: { ...(b.fields ?? fieldsOf(pd, b, type)) } };
   });
@@ -42,9 +58,18 @@ export function docOf(pd, w) {
     });
     byId.get(lowest).fields.parent = null;
   }
-  const nodes = blocks.map(({ b, type, fields }) => {
+  const nodes = blocks.map(({ b, type, fields, opaque }) => {
+    if (opaque) {
+      const content = [];
+      for (const r of b.runs) {
+        if (r.hole) continue;
+        if (r.br) content.push(schema.nodes.hard_break.create());
+        else content.push(schema.text(r.text, r.marks));
+      }
+      return type.create({ id: b.id, pos: null, raw: fields }, content);
+    }
     const attrs = { id: b.id, pos: null, ...fields };
-    if (type.name === "table" && Object.keys(attrs.rows ?? {}).length) return nodeFromBlock(schema, b.id, { t: "table", ...attrs });
+    if (type.name === "table" && Object.keys(attrs.rows ?? {}).length && Object.keys(attrs.cols ?? {}).length) return nodeFromBlock(schema, b.id, { t: "table", ...attrs });
     if (!type.isTextblock) return type.create(attrs);
     const content = [];
     for (const r of b.runs) {

package/src/page/ybind/group.js

@@ -6,6 +6,7 @@ import { LOCAL, HISTORY_META, attrKeys, defaultOf, mintId, mintOp } from "./layo
 import { tokensOf, tokenIndex, textTokenRange, projectionOf, yAfter, sameTok } from "./tokens.js";
 import { CHUNK_CHARS, insertTokens, applyRegion, markRange } from "./writer.js";
 import { walk } from "./walk.js";
+import { isOpaque, yjsFields } from "../format-codec.js";
 
 const { AddMarkStep, RemoveMarkStep, AttrStep, ReplaceStep, Mapping } = transform;
 
@@ -23,7 +24,7 @@ const touchesTable = (doc, from, to) => {
   return found;
 };
 
-export function localGroup(pd, transactions, w, stats, um = null, history = true, onFirstWrite = null) {
+export function localGroup(pd, transactions, w, stats, um = null, history = true, onFirstWrite = null, { join = false, open = false } = {}) {
   const first = () => { if (onFirstWrite) { const fn = onFirstWrite; onFirstWrite = null; fn(); } };
   const steps = [], docs = [], maps = [];
   for (const tr of transactions) tr.steps.forEach((s, i) => { steps.push(s); docs.push(tr.docs[i]); maps.push(s.getMap()); });
@@ -106,10 +107,18 @@ export function localGroup(pd, transactions, w, stats, um = null, history = true
       if (to <= from) continue;
       const name = step.mark.type.name;
       const val = step instanceof AddMarkStep ? (step.mark.attrs && Object.keys(step.mark.attrs).length ? { ...step.mark.attrs } : true) : null;
+      // An opaque mark is not a live key: adding it writes each descriptor it
+      // carries, and removing it erases nothing the command cannot understand.
+      if (isOpaque(step.mark)) {
+        if (val === null) continue;
+        const fields = yjsFields(step.mark.attrs.entries);
+        tx(() => { for (const [key, value] of Object.entries(fields)) markRange(markCtx, from, to, key, value, at); });
+        continue;
+      }
       tx(() => markRange(markCtx, from, to, name, val, at));
     }
   };
-  um?.stopCapturing();
+  if (!join) um?.stopCapturing();
   const timeout = um?.captureTimeout;
   if (um) um.captureTimeout = Infinity;
   try {
@@ -117,7 +126,7 @@ export function localGroup(pd, transactions, w, stats, um = null, history = true
     else pd.ydoc.transact((tr) => { tr.meta.set(HISTORY_META, history); first(); write(); }, LOCAL);
   } finally {
     if (um) um.captureTimeout = timeout;
-    um?.stopCapturing();
+    if (!open) um?.stopCapturing();
   }
   stats.groups++;
   stats.lastGroup = { chunked, structural, regional, span };

package/src/page/ybind/index.js

@@ -3,6 +3,8 @@ export * from "./tokens.js";
 export * from "./writer.js";
 export * from "./group.js";
 export * from "./bridge.js";
+export * from "./positions.js";
+export * from "./awareness.js";
 export * from "./seed.js";
 export * from "./origins.js";
 export * from "./recovery.js";

package/src/page/ybind/lineage.js

@@ -0,0 +1,71 @@
+import * as Y from "../../vendor/yjs.vendor.js";
+import { parseModel } from "../projection.js";
+import { blockFromItem } from "../adopt.js";
+import { seedClientId } from "./migrate.js";
+import { entriesOf } from "./parts.js";
+import { digestHex } from "./recovery-proof.js";
+
+// The seed client of an article: the Yjs client id seedPageFromArticle would write,
+// without building the seed. Two articles with the same blocks share it.
+export function seedLineage(article) {
+  const items = parseModel(article, { seed: article.getAttribute("data-rev") ?? "" });
+  if (!items.length) return { client: null };
+  const blocks = {};
+  items.forEach((item, i) => {
+    const block = blockFromItem(item, null);
+    block.pos = String(i + 1).padStart(8, "0");
+    blocks[item.id] = block;
+  });
+  return { client: seedClientId(blocks) };
+}
+
+export function valueClients(value) {
+  const clients = new Set();
+  for (const [, text] of entriesOf(value?.y ?? {})) {
+    try {
+      for (const client of Y.decodeStateVector(Y.encodeStateVectorFromUpdateV2(Y.fromBase64(text))).keys()) clients.add(client);
+    } catch {}
+  }
+  return clients;
+}
+
+export function sharesLineage(stored, incoming) {
+  const theirs = valueClients(stored);
+  const mine = valueClients(incoming);
+  if (!theirs.size || !mine.size || [...mine].some((client) => theirs.has(client))) return true;
+  const kept = new Map(entriesOf(stored?.y ?? {}));
+  return entriesOf(incoming?.y ?? {}).some(([key, text]) => kept.get(key) === text);
+}
+
+// May a journal written under `a` be replayed into a page under `b`? Same page
+// generation, and the same base bytes: an externally replaced article is another
+// generation even when it shows the same text.
+export function sameLineage(a, b) {
+  if (!a || !b || !a.generation || !b.generation) return false;
+  return a.generation === b.generation && a.baseDigest === b.baseDigest;
+}
+
+// The lineage a capsule records for its immutable base: the digest the host persists
+// and the state vector the page's own document had at the same moment.
+export async function lineageOf(generation, base) {
+  const bytes = base instanceof Uint8Array ? base : new Uint8Array(0);
+  return {
+    generation,
+    baseDigest: await digestHex(bytes),
+    baseVector: bytes.length ? Y.encodeStateVectorFromUpdateV2(bytes) : new Uint8Array(0),
+  };
+}
+
+// The existing ancestry check, with the empty case refused: an update with no client of
+// its own shares lineage with nothing, and neither does a page with no clients.
+export function sharesAncestry(stored, incoming) {
+  const theirs = valueClients(stored);
+  const mine = valueClients(incoming);
+  if (!theirs.size || !mine.size) return false;
+  return sharesLineage(stored, incoming);
+}
+
+export function seedOnly(doc, client) {
+  for (const id of Y.decodeStateVector(Y.encodeStateVector(doc)).keys()) if (id !== client) return false;
+  return Y.createDeleteSetFromStructStore(doc.store).clients.size === 0;
+}