@panphora/clayjs 1.13.1 → 1.15.0

package/src/server/rooms/live-data-tags.js

@@ -0,0 +1,49 @@
+import { load } from 'cheerio';
+import { parseStamp } from './live-data-ops.js';
+import { parseBy } from './live-provenance.js';
+
+const NAME = /^[A-Za-z0-9_.:-]{1,64}$/;
+
+// A browser with scripting on reads <noscript> as text, so a tag there is no live tag.
+const inert = (node) => {
+  for (let parent = node.parent; parent; parent = parent.parent) if (parent.name === 'template' || parent.name === 'noscript') return true;
+  return false;
+};
+
+/**
+ * The live tags in a document: inline JSON scripts with a valid merge name and
+ * the live token, outside <template> and <noscript>. A name used twice is skipped
+ * entirely unless includeDuplicates is requested for admission checks.
+ * Parsed with parse5, as a browser parses it: htmlparser2 is ten times faster
+ * but splits a tag differently on input outside writers can produce (a JSON
+ * string holding `<!--<script>`, scripts inside <svg> or <iframe>).
+ * @param {string} html
+ * @param {{ includeDuplicates?: boolean }} options
+ * @returns {{ name: string, ephemeral: boolean, text: string, at: { epoch: string, seq: number, hash: string } | null, by: { client: string, n: number } | null }[]}
+ */
+export function liveTags(html, { includeDuplicates = false } = {}) {
+  const $ = load(html);
+  const found = new Map();
+  const duplicated = new Set();
+  const all = [];
+  $('script[merge]').each((_, node) => {
+    const el = $(node);
+    if (inert(node) || el.attr('src') !== undefined) return;
+    const tokens = (el.attr('clay') || '').split(/\s+/);
+    if (!tokens.includes('live')) return;
+    const type = (el.attr('type') || '').split(';')[0].trim().toLowerCase();
+    if (type !== 'application/json' && !type.endsWith('+json')) return;
+    const name = el.attr('merge');
+    if (!NAME.test(name)) return;
+    const tag = { name, ephemeral: tokens.includes('ephemeral'), text: el.html() ?? '', at: parseStamp(el.attr('live-at')), by: parseBy(el.attr('live-by')) };
+    if (includeDuplicates) all.push(tag);
+    if (found.has(name)) {
+      duplicated.add(name);
+      return;
+    }
+    found.set(name, tag);
+  });
+  if (includeDuplicates) return all;
+  for (const name of duplicated) found.delete(name);
+  return [...found.values()];
+}

package/src/server/rooms/live-page-history.js

@@ -0,0 +1,41 @@
+import { randomUUID } from 'node:crypto';
+import { cloneJson, serializeLive } from './live-data-ops.js';
+
+export function makePageTransition({ room = null, format = 'yjs', sources = [], receipts = new Map() } = {}) {
+  const archived = new Map([...receipts].map(([key, receipt]) => [key, cloneJson(receipt)]));
+  const history = [...(room?.pageTransition?.history ?? [])];
+  if (archived.size) history.push({
+    epoch: room.epoch,
+    generation: room.pageTransition?.id ?? null,
+    receiptGeneration: room.receiptGeneration ?? 0,
+    sources: [...sources],
+    receipts: archived,
+  });
+  const transition = { v: 2, id: randomUUID(), format, sources: [...sources], receipts: archived, history };
+  transition.receiptCount = history.reduce((count, entry) => count + entry.receipts.size, 0);
+  const entries = history.map(({ epoch, generation, receiptGeneration, sources, receipts }) =>
+    [epoch, generation, receiptGeneration, sources, [...receipts]]);
+  transition.historyBytes = entries.reduce((bytes, entry) => bytes + Buffer.byteLength(serializeLive(entry), 'utf8'), 0);
+  transition.bytes = Buffer.byteLength(serializeLive([transition.v, transition.id, format, transition.sources, entries]), 'utf8');
+  return transition;
+}
+
+function ownReceipts(receipts, clientId) {
+  const mine = {};
+  if (clientId) for (const [key, receipt] of receipts) {
+    const split = key.indexOf('\n');
+    if (key.slice(split + 1) !== clientId) continue;
+    mine[key.slice(0, split)] = { seen: { [clientId]: receipt.n }, ...(receipt.saved?.length && { saved: receipt.saved }) };
+  }
+  return mine;
+}
+
+export function pageTransitionState(transition, clientId) {
+  const { v, id, format, sources, receipts, history } = transition;
+  return {
+    v, id, format, sources, receipts: ownReceipts(receipts, clientId),
+    history: history.map(({ epoch, generation, receiptGeneration, sources, receipts }) => ({
+      epoch, generation, receiptGeneration, sources, receipts: ownReceipts(receipts, clientId),
+    })),
+  };
+}

package/src/server/rooms/live-provenance.js

@@ -0,0 +1,142 @@
+const CLIENT = /^[A-Za-z0-9_-]{1,64}$/;
+const NUMBER = /^[1-9]\d{0,15}$/;
+export const RANGE_LIMIT = 256;
+export const RECEIPT_LIMIT = 4096;
+
+const integer = (text) => NUMBER.test(text) && Number.isSafeInteger(Number(text));
+
+export function unionRanges(...sets) {
+  const clients = new Map();
+  for (const set of sets) for (const [client, ranges] of set ?? []) {
+    if (!clients.has(client)) clients.set(client, []);
+    clients.get(client).push(...ranges.map(([lo, hi]) => [lo, hi]));
+  }
+  return [...clients].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([client, ranges]) => {
+    const out = [];
+    for (const [lo, hi] of ranges.sort((a, b) => a[0] - b[0])) {
+      const last = out[out.length - 1];
+      if (last && lo <= last[1] + 1) last[1] = Math.max(last[1], hi);
+      else out.push([lo, hi]);
+    }
+    return [client, out];
+  }).filter(([, ranges]) => ranges.length);
+}
+
+export const rangeCount = (set) => set.reduce((n, [, ranges]) => n + ranges.length, 0);
+export const hasNumber = (ranges, n) => !!ranges?.some(([lo, hi]) => lo <= n && n <= hi);
+export const contains = (set, client, n) => hasNumber(set?.find(([id]) => id === client)?.[1], n);
+export const identitySet = ([client, n]) => [[client, [[n, n]]]];
+export const frameSet = (by) => by?.v === 2 ? by.frames : by ? [[by.client, [[1, by.n]]]] : [];
+export const descendants = (by) => by?.v === 2 ? unionRanges(by.ancestors, identitySet(by.capture)) : [];
+
+function parseRanges(text) {
+  if (!text) return [];
+  const out = [];
+  let count = 0;
+  for (const part of text.split(';')) {
+    const fields = part.split(':');
+    if (fields.length !== 2 || !CLIENT.test(fields[0]) || !fields[1]) return null;
+    const ranges = [];
+    for (const raw of fields[1].split(',')) {
+      if (++count > RANGE_LIMIT) return null;
+      const ends = raw.split('-');
+      if (ends.length > 2 || !ends.every(integer)) return null;
+      const lo = Number(ends[0]), hi = Number(ends[1] ?? ends[0]);
+      if (hi < lo) return null;
+      ranges.push([lo, hi]);
+    }
+    out.push([fields[0], ranges]);
+  }
+  return unionRanges(out);
+}
+
+function printRanges(set) {
+  return unionRanges(set).map(([client, ranges]) => `${client}:${ranges.map(([lo, hi]) => lo === hi ? String(lo) : `${lo}-${hi}`).join(',')}`).join(';');
+}
+
+export function parseBy(text) {
+  if (typeof text !== 'string' || text.length > 32768) return null;
+  if (!text.startsWith('v2|')) {
+    const m = /^([A-Za-z0-9_-]{1,64}):([1-9]\d{0,15})$/.exec(text);
+    return m && integer(m[2]) ? { client: m[1], n: Number(m[2]) } : null;
+  }
+  const parts = text.split('|');
+  if (parts.length !== 4) return null;
+  const frames = parseRanges(parts[1]), ancestors = parseRanges(parts[2]);
+  const capture = /^([A-Za-z0-9_-]{1,64}):([1-9]\d{0,15})$/.exec(parts[3]);
+  if (!frames || !ancestors || !capture || !integer(capture[2])) return null;
+  if (rangeCount(frames) + rangeCount(ancestors) + 1 > RANGE_LIMIT) return null;
+  const id = [capture[1], Number(capture[2])];
+  if (contains(ancestors, ...id)) return null;
+  return { v: 2, frames, ancestors, capture: id };
+}
+
+export function formatBy(by) {
+  const text = `v2|${printRanges(by.frames)}|${printRanges(by.ancestors)}|${by.capture[0]}:${by.capture[1]}`;
+  return parseBy(text) ? text : null;
+}
+
+export function receiptHas(receipt, n) {
+  return !!receipt && (n <= receipt.n || hasNumber(receipt.saved, n));
+}
+
+export function receiptBytes(receipt) {
+  return receipt?.saved ? JSON.stringify({ saved: receipt.saved, savedSeq: receipt.savedSeq }).length : 0;
+}
+
+export function replaceReceipt(room, key, next) {
+  const delta = receiptBytes(next) - receiptBytes(room.lastN.get(key));
+  room.receiptBytes = (room.receiptBytes ?? 0) + delta;
+  room.lastN.delete(key);
+  room.lastN.set(key, next);
+  return delta;
+}
+
+export function retireReceipt(room, key) {
+  const bytes = receiptBytes(room.lastN.get(key));
+  room.lastN.delete(key);
+  room.receiptBytes = (room.receiptBytes ?? 0) - bytes;
+  room.receiptGeneration = (room.receiptGeneration ?? 0) + 1;
+  room.retiredReceipts ??= new Map();
+  room.retiredReceipts.delete(key);
+  room.retiredReceipts.set(key, room.receiptGeneration);
+  if (room.retiredReceipts.size > RECEIPT_LIMIT) room.retiredReceipts.delete(room.retiredReceipts.keys().next().value);
+  return -bytes;
+}
+
+export function saveReceipt(room, key, ranges, seq, limit, retained = null) {
+  const last = room.lastN.get(key);
+  if (!last && room.lastN.size >= limit) {
+    let victim;
+    for (const candidate of room.lastN.keys()) {
+      if (retained?.has(candidate)) continue;
+      victim = candidate;
+      break;
+    }
+    if (victim === undefined) return false;
+    retireReceipt(room, victim);
+  }
+  const next = last ? { ...last } : { n: 0, seq: 0 };
+  const kept = unionRanges([['r', next.saved ?? []]], [['r', ranges]])[0]?.[1]
+    .filter(([, hi]) => hi > next.n).map(([lo, hi]) => [Math.max(lo, next.n + 1), hi]) ?? [];
+  if (kept.length > RANGE_LIMIT) {
+    retireReceipt(room, key);
+    next.saved = kept.slice(-RANGE_LIMIT);
+    next.savedSeq = Math.max(next.savedSeq ?? 0, seq);
+  } else {
+    if (kept.length) {
+      next.saved = kept;
+      next.savedSeq = Math.max(next.savedSeq ?? 0, seq);
+    } else {
+      delete next.saved;
+      delete next.savedSeq;
+    }
+  }
+  replaceReceipt(room, key, next);
+  return true;
+}
+
+export function postReceipt(last, n, seq) {
+  const saved = (last?.saved ?? []).filter(([, hi]) => hi > n).map(([lo, hi]) => [Math.max(lo, n + 1), hi]);
+  return { n, seq, ...(saved.length && { saved, savedSeq: last.savedSeq }) };
+}

package/src/server/rooms/page-admission.js

@@ -0,0 +1,79 @@
+import { createHash } from 'node:crypto';
+import { parseJsonRelaxed } from 'hyper-morph/json-parse';
+import { cloneJson } from './live-data-ops.js';
+import { liveTags } from './live-data-tags.js';
+import { recent } from './recent.js';
+
+const PAGE = /^page(\.[0-9]+)?$/;
+const PART = /^(.+)\.(\d+)\.(\d+)$/;
+const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+export const isHybridPageValue = (value) => record(value) && record(value.blocks) && (value.deleted == null || record(value.deleted)) && Object.keys(value).every((key) => key === 'blocks' || key === 'deleted');
+
+export function isYPageValue(value, { complete = true } = {}) {
+  if (!record(value) || value.v !== 1 || !record(value.y) || Object.keys(value).some((key) => !['v', 'g', 'y'].includes(key))) return false;
+  const whole = new Set();
+  const groups = new Map();
+  for (const [key, text] of Object.entries(value.y)) {
+    if (typeof text !== 'string') return false;
+    const part = PART.exec(key);
+    if (!part) {
+      whole.add(key);
+      continue;
+    }
+    const index = Number(part[2]);
+    const count = Number(part[3]);
+    if (!Number.isSafeInteger(index) || !Number.isSafeInteger(count) || count < 1 || index >= count) return false;
+    const group = groups.get(part[1]) ?? { count, indices: new Set() };
+    if (group.count !== count || group.indices.has(index)) return false;
+    group.indices.add(index);
+    groups.set(part[1], group);
+  }
+  for (const [key, group] of groups) {
+    if (whole.has(key) || (complete && group.indices.size !== group.count)) return false;
+  }
+  return true;
+}
+
+// Callers get their own copy of the tags, so none can change another's answer.
+export function inspectPage(html) {
+  const answer = inspected(html);
+  return { ...answer, tags: cloneJson(answer.tags) };
+}
+
+const inspected = recent(4, (html) => {
+  if (!/merge/i.test(html)) return { kind: 'none', tags: [] };
+  const source = liveTags(html, { includeDuplicates: true }).filter((tag) => PAGE.test(tag.name));
+  if (!source.length) return { kind: 'none', tags: [] };
+  const names = new Set();
+  const tags = [];
+  for (const tag of source) {
+    if (names.has(tag.name)) return { kind: 'invalid', reason: 'duplicate-tag', tags: [] };
+    names.add(tag.name);
+    if (tag.ephemeral) return { kind: 'invalid', reason: 'ephemeral-tag', tags: [] };
+    try {
+      tags.push([tag.name, cloneJson(parseJsonRelaxed(tag.text))]);
+    } catch {
+      return { kind: 'invalid', reason: 'invalid-json', tags: [] };
+    }
+  }
+  if (tags.some(([, value]) => record(value) && (Object.hasOwn(value, 'y') || Object.hasOwn(value, 'v')))) {
+    if (tags.length !== 1 || tags[0][0] !== 'page' || !isYPageValue(tags[0][1])) return { kind: 'invalid', reason: 'invalid-yjs', tags };
+    return { kind: 'yjs', tags };
+  }
+  return { kind: tags.every(([, value]) => isHybridPageValue(value)) ? 'hybrid' : 'other', tags };
+});
+
+const canon = (value) => (Array.isArray(value) ? `[${value.map(canon).join(',')}]` : value && typeof value === 'object' ? `{${Object.keys(value).sort().map((key) => JSON.stringify(key) + ':' + canon(value[key])).join(',')}}` : JSON.stringify(value ?? null));
+
+export function pageBaseline(tags) {
+  if (!Array.isArray(tags) || !tags.length) throw new TypeError('Expected named hybrid page tags');
+  const names = new Set();
+  const source = tags.map((tag) => {
+    if (!Array.isArray(tag) || tag.length !== 2 || typeof tag[0] !== 'string' || !PAGE.test(tag[0]) || names.has(tag[0])) throw new TypeError('Expected unique page tag names');
+    names.add(tag[0]);
+    const value = cloneJson(tag[1]);
+    if (!isHybridPageValue(value)) throw new TypeError('Expected a hybrid page value');
+    return [tag[0], value];
+  });
+  return createHash('sha256').update(canon(source), 'utf8').digest('hex');
+}

package/src/server/rooms/page-conversion.js

@@ -0,0 +1,62 @@
+import { ifMatchSatisfied } from './spec-wire.js';
+import { inspectPage, pageBaseline } from './page-admission.js';
+
+const PAGE = /^page(\.[0-9]+)?$/;
+const BASE = /^[0-9a-f]{64}$/;
+const EPOCH = /^[A-Za-z0-9-]{1,64}$/;
+
+export class PageConversionError extends Error {
+  constructor(reason) {
+    super(`Page conversion refused: ${reason}`);
+    this.name = 'PageConversionError';
+    this.reason = reason;
+  }
+}
+
+const refuse = (reason) => { throw new PageConversionError(reason); };
+
+export function parsePageConversion(header) {
+  if (header === undefined || header === null) return null;
+  if (typeof header !== 'string') refuse('invalid-header');
+  const [version, ...fields] = header.split(';').map((part) => part.trim());
+  if (version !== 'v1') refuse('invalid-header');
+  const params = new Map();
+  for (const field of fields) {
+    const pair = field.split('=').map((part) => part.trim());
+    if (pair.length !== 2 || !['source', 'base', 'epoch'].includes(pair[0]) || !pair[1] || params.has(pair[0])) refuse('invalid-header');
+    params.set(pair[0], pair[1]);
+  }
+  const source = params.get('source');
+  const base = params.get('base');
+  const epoch = params.get('epoch');
+  if (!['file', 'room'].includes(source) || !BASE.test(base ?? '')) refuse('invalid-header');
+  if (source === 'file' ? params.has('epoch') : !EPOCH.test(epoch ?? '')) refuse('invalid-header');
+  return { source, base, epoch: epoch ?? null };
+}
+
+// A null result means no explicit conversion request, not approval of an ordinary save.
+export function checkPageConversion({ header, currentHtml, html, ifMatch, room = null }) {
+  const request = parsePageConversion(header);
+  if (!request) return null;
+  if (typeof ifMatch !== 'string' || ifMatch.trim() === '*' || ifMatch.includes(',') || !ifMatchSatisfied(ifMatch, currentHtml)) refuse('file-changed');
+  const before = inspectPage(currentHtml);
+  const after = inspectPage(html);
+  if (before.kind !== 'hybrid') refuse('invalid-source');
+  if (after.kind !== 'yjs') refuse('invalid-capture');
+  const stores = new Map([...(room?.stores ?? [])].filter(([name]) => PAGE.test(name)));
+  if (request.source === 'file' && stores.size) refuse('room-required');
+  if (request.source === 'room') {
+    if (!stores.size || request.epoch !== room?.epoch) refuse('room-changed');
+    const names = new Set(before.tags.map(([name]) => name));
+    if ([...stores].some(([name, store]) => !names.has(name) || store.ephemeral)) refuse('ambiguous-source');
+  }
+  const tags = before.tags.map(([name, value]) => [name, stores.has(name) ? stores.get(name).value : value]);
+  let baseline;
+  try {
+    baseline = pageBaseline(tags);
+  } catch {
+    refuse('invalid-source');
+  }
+  if (baseline !== request.base) refuse('source-changed');
+  return { ...request, names: tags.map(([name]) => name), value: after.tags[0][1] };
+}

package/src/server/rooms/page-rebase.js

@@ -0,0 +1,108 @@
+import { load } from 'cheerio';
+import { merge3, mergeJson } from 'hyper-morph';
+import { parseJsonRelaxed } from 'hyper-morph/json-parse';
+import { project, parseModel, renderModel, fragmentCleaner } from '../../page/projection.js';
+import { blocksFromPageValues } from '../../page/ybind/decode.js';
+import { mergePageModels } from '../../page/merge.js';
+import { inert, pageRev } from './page-state.js';
+
+// The lone article of html: its element rebuilt in doc, and where its start tag
+// and its contents sit in html.
+function articleOf(html, doc) {
+  const $ = load(html, { sourceCodeLocationInfo: true });
+  const nodes = $('article[data-page]').toArray().filter((node) => !inert(node));
+  if (nodes.length !== 1) return null;
+  const loc = nodes[0].sourceCodeLocation;
+  if (!loc?.startTag || !loc?.endTag) return null;
+  const article = doc.createElement('article');
+  for (const [name, value] of Object.entries(nodes[0].attribs)) article.setAttribute(name, value);
+  article.innerHTML = html.slice(loc.startTag.endOffset, loc.endTag.startOffset);
+  return { article, startTag: loc.startTag, inner: [loc.startTag.endOffset, loc.endTag.startOffset] };
+}
+
+// The article's start tag with its data-rev replaced or added, using the
+// attribute's own location so a data-rev inside another value is left alone.
+function stampOpen(html, startTag, rev) {
+  const at = startTag.attrs?.['data-rev'];
+  if (!at) return `${html.slice(startTag.startOffset, startTag.endOffset - 1)} data-rev="${rev}">`;
+  return html.slice(startTag.startOffset, at.startOffset) + `data-rev="${rev}"` + html.slice(at.endOffset, startTag.endOffset);
+}
+
+function tagValue(tag, doc) {
+  const holder = doc.createElement('div');
+  holder.innerHTML = tag;
+  const script = holder.querySelector('script');
+  return script ? parseJsonRelaxed(script.textContent) : null;
+}
+
+// An outside writer's page rebased onto the stored page. base is the version the
+// writer started from (its article carries the incoming data-rev), current the
+// stored file, state the stored page record ({ v, rev, tag }). The result is the
+// incoming document with a merged article stamped with state.rev, so the host
+// composes the record back in and open tabs adopt it as a hand edit. Null when
+// there is nothing to rebase: no record, the writer already had the stored rev,
+// or the inputs do not line up.
+export function rebasePage({ storedHtml, state, incomingHtml, baseHtml, createDocument }) {
+  if (!state || state.v !== 1 || !state.rev || typeof state.tag !== 'string') return null;
+  const rev = pageRev(incomingHtml);
+  if (!rev || rev === state.rev) return null;
+  if (pageRev(baseHtml) !== rev || pageRev(storedHtml) !== state.rev) return null;
+  const doc = createDocument();
+  const value = tagValue(state.tag, doc);
+  if (!value) return null;
+  const blocks = blocksFromPageValues([value]);
+  const known = new Map(project(blocks).map((item) => [item.id, item]));
+  const incoming = articleOf(incomingHtml, doc);
+  const base = articleOf(baseHtml, doc);
+  const stored = articleOf(storedHtml, doc);
+  if (!incoming || !base || !stored) return null;
+  const merged = mergePageModels(
+    parseModel(base.article, { seed: rev, known }),
+    parseModel(stored.article, { seed: state.rev, known }),
+    parseModel(incoming.article, { seed: rev, known }),
+    { doc, merge3, mergeJson },
+  );
+  const fallbackOf = (id) => (typeof blocks[id]?.artifact?.fallbackHtml === 'string' ? blocks[id].artifact.fallbackHtml : '');
+  const inner = `\n${renderModel(merged.items, { fallbackOf, clean: fragmentCleaner(doc) })}\n`;
+  const [innerStart, innerEnd] = incoming.inner;
+  const open = stampOpen(incomingHtml, incoming.startTag, state.rev);
+  const html = incomingHtml.slice(0, incoming.startTag.startOffset) + open + inner + incomingHtml.slice(innerEnd);
+  return { html, conflicts: merged.conflicts };
+}
+
+// Of the versions carrying the incoming body's rev, newest first, the one it was
+// most likely copied from: the one sharing the most blocks with it, the oldest on
+// a tie. A hand edit that kept the rev is a second such version, and merging a
+// writer that copied the first one onto it would undo that hand edit.
+export function closestBase(candidates, incomingHtml, createDocument) {
+  if (candidates.length <= 1) return candidates[0] ?? null;
+  const doc = createDocument();
+  const rev = pageRev(incomingHtml);
+  const blocksOf = (html) => {
+    const found = articleOf(html, doc);
+    return found ? parseModel(found.article, { seed: rev, known: new Map() }).map((item) => JSON.stringify(item)) : null;
+  };
+  const incoming = blocksOf(incomingHtml);
+  if (!incoming) return candidates[candidates.length - 1];
+  const wanted = new Set(incoming);
+  let best = candidates[candidates.length - 1];
+  let most = -1;
+  for (const html of candidates) {
+    const blocks = blocksOf(html);
+    const shared = blocks ? blocks.filter((block) => wanted.has(block)).length : -1;
+    if (shared >= most) { best = html; most = shared; }
+  }
+  return best;
+}
+
+// The page document with its article stamped with rev: a version restored as an
+// edit carries the stored rev, so open tabs merge it onto the page they have.
+export function stampPageRev(html, rev) {
+  if (typeof html !== 'string' || !rev) return null;
+  const $ = load(html, { sourceCodeLocationInfo: true });
+  const nodes = $('article[data-page]').toArray().filter((node) => !inert(node));
+  const loc = nodes.length === 1 ? nodes[0].sourceCodeLocation?.startTag : null;
+  if (!loc) return null;
+  const stamped = stampOpen(html, loc, rev);
+  return html.slice(0, loc.startOffset) + stamped + html.slice(loc.endOffset);
+}

package/src/server/rooms/page-state.js

@@ -0,0 +1,91 @@
+import { load } from 'cheerio';
+import { inspectPage } from './page-admission.js';
+import { recent } from './recent.js';
+
+export const inert = (node) => {
+  for (let parent = node.parent; parent; parent = parent.parent) if (parent.name === 'template' || parent.name === 'noscript') return true;
+  return false;
+};
+
+const span = (node) => {
+  const loc = node.sourceCodeLocation;
+  return loc ? { startOffset: loc.startOffset, endOffset: loc.endOffset } : null;
+};
+
+// Offsets only, never the parsed tree, so the remembered answers stay small.
+const locate = recent(4, (html) => {
+  const $ = load(html, { sourceCodeLocationInfo: true });
+  const articles = $('article[data-page]').toArray().filter((node) => !inert(node));
+  const tags = $('script[merge="page"]').toArray().filter((node) => !inert(node) &&
+    ($(node).attr('clay') || '').split(/\s+/).includes('live'));
+  return Object.freeze({
+    articles: articles.length,
+    tags: tags.length,
+    rev: articles.length === 1 ? $(articles[0]).attr('data-rev') || null : null,
+    article: articles.length === 1 ? span(articles[0]) : null,
+    tag: tags.length === 1 ? span(tags[0]) : null,
+  });
+});
+
+export function pageRev(html) {
+  if (typeof html !== 'string') return null;
+  return locate(html).rev;
+}
+
+const lineStart = (html, at) => {
+  for (let i = at - 1; i >= 0; i--) if (html[i] === '\n' || html[i] === '\r') return i + 1;
+  return 0;
+};
+
+const lineEnd = (html, at) => {
+  for (let i = at; i < html.length; i++) {
+    if (html[i] === '\n') return i + 1;
+    if (html[i] === '\r') return html[i + 1] === '\n' ? i + 2 : i + 1;
+  }
+  return html.length;
+};
+
+const newlineOf = (html, from) => {
+  const before = html.slice(Math.max(0, from - 2), from);
+  if (before.endsWith('\r\n')) return '\r\n';
+  if (before.endsWith('\n')) return '\n';
+  if (before.endsWith('\r')) return '\r';
+  const first = /\r\n|\r|\n/.exec(html);
+  return first ? first[0] : '\n';
+};
+
+const spanOf = (html, loc) => {
+  let start = loc.startOffset;
+  let end = loc.endOffset;
+  const from = lineStart(html, start);
+  const to = lineEnd(html, end);
+  if (!/\S/.test(html.slice(from, start)) && !/\S/.test(html.slice(end, to))) { start = from; end = to; }
+  return [start, end];
+};
+
+// The stored file and the page tag it held, or the html unchanged with no state
+// when it is not exactly one Yjs page tag beside exactly one revisioned article.
+// A tag with no revisioned article stays in the file: there it is the only copy
+// of the page, and no record could hold it.
+export function splitPage(html) {
+  if (typeof html !== 'string' || inspectPage(html).kind !== 'yjs') return { file: html, state: null };
+  const { articles, tags, rev, article, tag: loc } = locate(html);
+  if (articles !== 1 || tags !== 1 || !rev) return { file: html, state: null };
+  if (!article || !loc || (loc.startOffset < article.endOffset && loc.endOffset > article.startOffset)) return { file: html, state: null };
+  const [start, end] = spanOf(html, loc);
+  return { file: html.slice(0, start) + html.slice(end), state: { v: 1, rev, tag: html.slice(loc.startOffset, loc.endOffset) } };
+}
+
+// The document an editor sees: the file with the stored page tag put back
+// before its article, when the record still belongs to that article.
+export function composePage(file, state) {
+  if (typeof file !== 'string' || !state || state.v !== 1 || typeof state.tag !== 'string' || !state.rev) return file;
+  if (inspectPage(file).kind !== 'none') return file;
+  const { articles, rev, article } = locate(file);
+  if (articles !== 1 || rev !== state.rev || !article) return file;
+  const at = article.startOffset;
+  const from = lineStart(file, at);
+  const indent = file.slice(from, at);
+  const insert = /\S/.test(indent) ? state.tag : `${state.tag}${newlineOf(file, from)}${indent}`;
+  return file.slice(0, at) + insert + file.slice(at);
+}

package/src/server/rooms/page-write-admission.js

@@ -0,0 +1,63 @@
+import { parseJsonRelaxed } from 'hyper-morph/json-parse';
+import { liveTags } from './live-data-tags.js';
+import { inspectPage } from './page-admission.js';
+import { checkPageConversion, PageConversionError } from './page-conversion.js';
+import { PageFormatError } from './page-write-guard.js';
+import { ifMatchSatisfied } from './spec-wire.js';
+
+const PAGE = /^page(\.[0-9]+)?$/;
+const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const refuse = (reason) => { throw new PageConversionError(reason); };
+
+function claimsYPage(html) {
+  if (!/merge/i.test(html)) return false;
+  return liveTags(html, { includeDuplicates: true }).some((tag) => {
+    if (!PAGE.test(tag.name)) return false;
+    try {
+      const value = parseJsonRelaxed(tag.text);
+      return record(value) && value.v === 1 && record(value.y);
+    } catch {
+      return false;
+    }
+  });
+}
+
+function checkInitialRoom(room) {
+  if ([...(room?.stores.keys() ?? [])].some((name) => PAGE.test(name)) ||
+    [...(room?.lastN.keys() ?? [])].some((key) => PAGE.test(key.slice(0, key.indexOf('\n')))) ||
+    (room?.pageTransition && room.pageTransition.format !== 'none')) refuse('room-page-authority');
+}
+
+function checkInitialCondition(ifMatch, currentHtml) {
+  if (typeof ifMatch !== 'string' || ifMatch.trim() === '*' || ifMatch.includes(',') ||
+    !ifMatchSatisfied(ifMatch, currentHtml)) refuse('file-changed');
+}
+
+export function checkPageInitial({ currentHtml, html, ifMatch, room = null }) {
+  if (typeof currentHtml !== 'string' || inspectPage(currentHtml).kind !== 'none') refuse('invalid-source');
+  if (typeof html !== 'string' || inspectPage(html).kind !== 'yjs') refuse('invalid-capture');
+  checkInitialRoom(room);
+  checkInitialCondition(ifMatch, currentHtml);
+}
+
+export function checkPageWriteAdmission({ currentHtml, html, header = null, ifMatch, room = null }) {
+  const before = inspectPage(currentHtml ?? '');
+  const after = inspectPage(html ?? '');
+  const converted = before.kind === 'yjs' || room?.pageTransition?.format === 'yjs';
+  if (converted && after.kind === 'none' && header == null) return 'ordinary';
+  if (converted && after.kind !== 'yjs') throw new PageFormatError();
+  if (header !== null && header !== undefined) {
+    checkPageConversion({ header, currentHtml, html, ifMatch, room });
+    return 'conversion';
+  }
+  if (converted) return 'ordinary';
+  if (after.kind !== 'yjs') {
+    if (after.kind === 'invalid' && claimsYPage(html ?? '') && !claimsYPage(currentHtml ?? '')) refuse('invalid-capture');
+    return 'ordinary';
+  }
+  if (before.kind === 'hybrid') refuse('implicit-conversion');
+  if (before.kind !== 'none' || typeof currentHtml !== 'string') refuse('invalid-source');
+  checkInitialRoom(room);
+  checkInitialCondition(ifMatch, currentHtml);
+  return 'initial';
+}

package/src/server/rooms/page-write-guard.js

@@ -0,0 +1,23 @@
+import { inspectPage } from './page-admission.js';
+
+export class PageFormatError extends Error {
+  constructor() {
+    super('A converted page must retain one complete Yjs page value');
+    this.name = 'PageFormatError';
+    this.code = 'page-format';
+    this.statusCode = 409;
+  }
+}
+
+export function checkPageWriteFormat({ currentHtml, html, room = null }) {
+  if (room?.pageTransition?.format !== 'yjs' && inspectPage(currentHtml ?? '').kind !== 'yjs') return;
+  const kind = inspectPage(html ?? '').kind;
+  if (kind !== 'yjs' && kind !== 'none') throw new PageFormatError();
+}
+
+// A Yjs page room whose lineage the written document no longer carries: an
+// outside edit or restore replaced the article, so the room's unsaved page
+// edits belong in a recovered copy and the room must start over.
+export function pageLineageLost(room, html) {
+  return room?.pageTransition?.format === 'yjs' && room.stores.has('page') && inspectPage(html ?? '').kind === 'none';
+}