@panphora/clayjs 1.15.2 → 1.16.0

package/src/recovery/undo.js

@@ -0,0 +1,257 @@
+/**
+ * undo.js — the durable half of a refused undo step.
+ *
+ * The undo stack belongs to this tab and this editing session: a reload starts with an
+ * empty history, and the entry a person tried to take back is live DOM nodes and a
+ * compiled replay plan, neither of which a reload can use. What a reload can keep is
+ * the losing side as plain data — the label, the direction, why it was refused, the
+ * targets with the page's own name for each, and every step's before and after.
+ *
+ * One internal channel, `clay.undo`, on the shared recovery service: registered the
+ * first time a step is refused or the page keeps one of its own, never at boot and
+ * never by a reader. A refused record is never the kind a save can cover, and this
+ * channel registers nothing a save could read back, so a normal save dismisses
+ * nothing here that a person has not dealt with. A record is still only a recovery
+ * copy: it is not a save and the page never renders from it.
+ */
+
+import { representedEtag } from '../core/etag.js';
+import { storage } from '../lib/doc-storage.js';
+import { plainCopy, storedContext } from './conflicts.js';
+
+export const UNDO_CHANNEL = 'clay.undo';
+export const UNDO_VERSION = 1;
+export const UNDO_KIND = 'conflict';
+export const UNDO_TEXT = 'text';
+
+// The same cheap read the conflicts channel keeps for the notice's shell: one small
+// count in this document's own storage, so the next edit session learns that copies
+// are waiting without opening the database. It is written here, on stage and on
+// dismissal, and never read from the reader path, which loads neither module.
+const HINT_KEY = 'undo';
+
+/**
+ * How many copies this document's store is holding for review, without opening the
+ * database. Zero means a boot has nothing to show.
+ *
+ * @returns {number}
+ */
+export function pendingUndo() {
+  const stored = storage.local.get(HINT_KEY);
+  return Number.isFinite(stored?.count) && stored.count > 0 ? stored.count : 0;
+}
+
+function noteHint(count) {
+  if (count > 0) storage.local.set(HINT_KEY, { count, at: Date.now() });
+  else storage.local.remove(HINT_KEY);
+}
+
+function recoveryService() {
+  const clay = globalThis.window?.clay ?? globalThis.clay;
+  return clay?.recovery ?? null;
+}
+
+let registered = null;
+
+function channel() {
+  const service = recoveryService();
+  if (!service || typeof service.register !== 'function') return null;
+  if (registered?.service === service) return registered.channel;
+  try {
+    registered = {
+      service,
+      channel: service.register({ channel: UNDO_CHANNEL, version: UNDO_VERSION }),
+    };
+  } catch (_) {
+    return null;
+  }
+  return registered.channel;
+}
+
+// One refused step and one direction are one record: the key is what a repeated click
+// lands on, and what lets the older copy go.
+const keyOf = (entryId, direction) => `refused:${entryId}:${direction}`;
+
+function elementFor(id) {
+  if (id == null || typeof document === 'undefined') return null;
+  const escaped = globalThis.CSS?.escape ? globalThis.CSS.escape(String(id)) : String(id).replace(/["\\]/g, '\\$&');
+  try {
+    return document.querySelector(`[data-id="${escaped}"]`);
+  } catch (_) {
+    return null;
+  }
+}
+
+// The registry itself stays with the ledger: `clay.conflicts` is where a page registered
+// its resolver, and asking it here costs no module the reader carries and no download.
+function pageRegistry() {
+  const clay = globalThis.window?.clay ?? globalThis.clay;
+  const conflicts = clay?.conflicts;
+  return typeof conflicts?.contextFor === 'function' ? conflicts : null;
+}
+
+/**
+ * The page's name for one refused target, asked of the same resolver registry the
+ * conflict notice uses — the ledger's own `contextFor`, so the order, the throw and the
+ * fields kept are one behaviour and not two.
+ *
+ * The subject is the target's id and the live element that id finds, which a resolver
+ * written for the conflict ledger answers nothing for: it reads the record's own nodes,
+ * and a refused step has none. Such a page gets the generic shape until it names this
+ * subject too.
+ *
+ * @param {{id: ?string}} target
+ * @returns {Object}
+ */
+export function contextForTarget({ id = null } = {}) {
+  const target = id == null ? null : String(id);
+  const registry = pageRegistry();
+  const found = registry ? registry.contextFor({ source: 'undo', id: target, element: elementFor(target) }, null) : null;
+  return found ?? { kind: null, id: target, label: null, field: null };
+}
+
+// One context per refused target, in the targets' own order.
+function contextsOf(targets) {
+  return targets.map((target) => storedContext(contextForTarget(target)));
+}
+
+// A step refused twice is the same losing material. The older record goes only once
+// the newer one is durable, and only at the revision this tab can see, so a copy
+// another tab replaced or a person dismissed is never removed by a guess.
+async function supersede(ch, key, id) {
+  let listed;
+  try {
+    listed = await ch.list();
+  } catch (_) {
+    return;
+  }
+  if (!listed?.ok) return;
+  for (const record of listed.records) {
+    if (record.key !== key || String(record.id) === String(id)) continue;
+    try {
+      await ch.dismiss(record.id, { revision: record.revision });
+    } catch (_) {}
+  }
+}
+
+// The whole stage, flush and supersede of one refusal, one call at a time: two refusals
+// in the same tick would otherwise each delete the other's record as the older copy.
+let keeping = Promise.resolve();
+
+/**
+ * Keep what a refused undo or redo would have restored, before anything in this tab
+ * can be lost to a reload.
+ *
+ * The engine's own `describe(entryId)` is the source: it is plain data already, with
+ * the refusal on it and every step's endpoints, so nothing here reads a DOM node or a
+ * replay plan. A store that refuses the write leaves the copy in memory — the service
+ * keeps it — and answers with the failure.
+ *
+ * @param {Object} engine - the started undo scope (`clay.undo`)
+ * @param {{entryId: string, direction: string, code?: string}} receipt
+ * @returns {Promise<{ok: boolean, code?: string}>}
+ */
+export function keepRefusal(engine, receipt) {
+  const run = keeping.then(() => keepRefusalNow(engine, receipt));
+  keeping = run.catch(() => {});
+  return run;
+}
+
+async function keepRefusalNow(engine, receipt) {
+  const ch = channel();
+  if (!ch) return { ok: false, code: 'unavailable' };
+  let described = null;
+  try {
+    described = engine?.describe?.(receipt?.entryId) ?? null;
+  } catch (_) {
+    described = null;
+  }
+  if (!described) return { ok: false, code: 'unknown-entry' };
+  const refused = described.refused && typeof described.refused === 'object' ? described.refused : {};
+  const direction = receipt?.direction ?? refused.direction ?? null;
+  const targets = (Array.isArray(refused.targets) ? refused.targets : []).map((target) => ({
+    id: target?.id == null ? null : String(target.id),
+    kind: target?.kind == null ? null : String(target.kind),
+  }));
+  const key = keyOf(described.id ?? receipt?.entryId, direction);
+  const payload = plainCopy({
+    label: described.label ?? null,
+    direction,
+    code: receipt?.code ?? refused.code ?? null,
+    targets,
+    context: contextsOf(targets),
+    steps: described.steps ?? [],
+  }, [], '');
+  let staged;
+  try {
+    staged = ch.stage({ key, kind: UNDO_KIND, baseEtag: representedEtag() ?? null, base: null, payload });
+  } catch (err) {
+    console.error('clayjs: the refused step could not be kept for a later reload; it is still in this tab\'s history', err);
+    return { ok: false, code: 'error' };
+  }
+  const written = await ch.flush();
+  if (written?.ok) {
+    await supersede(ch, key, staged.id);
+    await kept();
+  }
+  return written?.ok ? written : { ok: false, code: written?.code || 'error' };
+}
+
+/**
+ * Keep one of the page's own records on the same channel: an app's unsent text or its
+ * own unreviewed conflict material, staged under `app:<key>`.
+ *
+ * @param {{key: string, label?: ?string, context?: ?Object, payload?: ?Object}} spec
+ * @returns {Promise<{ok: boolean, code?: string}>}
+ */
+export async function keep({ key, label = null, context = null, payload = null } = {}) {
+  const ch = channel();
+  if (!ch) return { ok: false, code: 'unavailable' };
+  const name = key == null ? '' : String(key);
+  if (!name) return { ok: false, code: 'invalid' };
+  const body = payload && typeof payload === 'object' ? payload : {};
+  const record = plainCopy({ ...body, label, context: storedContext(context) }, [], '');
+  try {
+    ch.stage({ key: `app:${name}`, kind: typeof body.text === 'string' ? UNDO_TEXT : UNDO_KIND, payload: record });
+  } catch (err) {
+    console.error('clayjs: the app\'s recovery copy could not be kept; it is still in this tab only', err);
+    return { ok: false, code: 'error' };
+  }
+  const written = await ch.flush();
+  if (written?.ok) await kept();
+  return written;
+}
+
+/**
+ * What this document's store holds for review, from every writer: a record belongs to
+ * the document, not to the tab that made it.
+ *
+ * @returns {Promise<{ok: boolean, code?: string, records: Object[], status?: Object}>}
+ */
+export async function kept() {
+  const ch = channel();
+  if (!ch) return { ok: true, records: [] };
+  const listed = await ch.list();
+  if (listed?.ok) noteHint(Array.isArray(listed.records) ? listed.records.length : 0);
+  return listed;
+}
+
+/**
+ * Remove one kept record, at the revision the reviewer was looking at. A record that
+ * moved since then is left exactly as it is.
+ *
+ * @param {*} id
+ * @param {{revision?: number}} [options]
+ * @returns {Promise<{ok: boolean, code?: string}>}
+ */
+export async function dismissKept(id, { revision } = {}) {
+  const ch = channel();
+  if (!ch) return { ok: false, code: 'unavailable' };
+  const receipt = await ch.dismiss(id, { revision });
+  if (receipt?.ok) {
+    try {
+      await kept();
+    } catch (_) {}
+  }
+  return receipt;
+}

package/src/server/checkpoint/index.js

@@ -3,12 +3,14 @@ import { parseJsonRelaxed } from 'hyper-morph/json-parse';
 import { cloneJson, formatBy, serializeLive, stampOf, textHash, unionRanges } from '../rooms/index.js';
 import { blocksFromYValue } from '../../page/ybind/decode.js';
 import { YDecodeError } from '../../page/ybind/provider.js';
-import { canon, fragmentCleaner, renderBlocks } from '../../page/projection.js';
+import { MARKS, OPAQUE, canon, fragmentCleaner, renderBlocks } from '../../page/projection.js';
 import { classifyFile, readBack } from '../../page/adopt.js';
 import { merge3, mergeJson } from 'hyper-morph';
 import { mergePageModels } from '../../page/merge.js';
+import { documentTitle } from '../../page/document-title.js';
 
 const PAGE = /^page(\.[0-9]+)?$/;
+const TITLE_MODE = 'clay-seo-title-mode';
 const NAME = /^[A-Za-z0-9_.:-]{1,64}$/;
 const attr = (node, name) => node.attrs.find((item) => item.name === name)?.value;
 const escapeAttr = (value) => value.replace(/&/g, '&').replace(/"/g, '"');
@@ -36,9 +38,19 @@ function inspect(html) {
   const tags = new Map();
   const duplicates = new Set();
   const articles = [];
+  const titleModes = [];
+  let head = null;
+  let body = null;
+  let title = null;
   function visit(node, inert = false) {
     if (!node.tagName) { for (const child of node.childNodes ?? []) visit(child, inert); return; }
     const blocked = inert || node.tagName === 'template' || node.tagName === 'noscript';
+    if (!blocked && node.tagName === 'head') head = node;
+    if (!blocked && node.tagName === 'body') body = node;
+    if (!blocked && node.parentNode === head && node.tagName === 'title' && !title) title = node;
+    if (!blocked && node.parentNode === head && node.tagName === 'meta' && (attr(node, 'name') ?? '').trim().toLowerCase() === TITLE_MODE) {
+      titleModes.push(attr(node, 'content'));
+    }
     if (!blocked && node.tagName === 'article' && attr(node, 'data-page') !== undefined) articles.push(node);
     if (!blocked && node.tagName === 'script' && attr(node, 'src') === undefined &&
       (attr(node, 'clay') ?? '').split(/\s+/).includes('live')) {
@@ -54,7 +66,7 @@ function inspect(html) {
   }
   visit(root);
   for (const name of duplicates) tags.delete(name);
-  return { article: articles.length === 1 ? articles[0] : null, tags };
+  return { article: articles.length === 1 ? articles[0] : null, tags, head, body, title, titleModes };
 }
 
 function startTag(html, node, store) {
@@ -87,7 +99,7 @@ function projection(capture) {
 }
 
 function placements(html, capture) {
-  const { article, tags } = inspect(html);
+  const { article, tags, head, body, title, titleModes } = inspect(html);
   if (!article?.sourceCodeLocation?.startTag || !article.sourceCodeLocation.endTag ||
     capture.stores.some((store) => !tags.get(store.name)?.sourceCodeLocation?.endTag ||
       (attr(tags.get(store.name), 'clay') ?? '').split(/\s+/).includes('ephemeral'))) return null;
@@ -97,7 +109,7 @@ function placements(html, capture) {
     const tag = tags.get(store.name).sourceCodeLocation;
     return tag.startOffset < articleEnd && tag.endOffset > articleStart;
   })) return null;
-  return { article, tags };
+  return { article, tags, head, body, title, titleModes };
 }
 
 function replace(html, edits) {
@@ -105,6 +117,46 @@ function replace(html, edits) {
     out.slice(0, edit.start) + edit.text + out.slice(edit.end), html);
 }
 
+const customTitleOf = (titleModes) =>
+  titleModes.some((content) => String(content ?? '').trim().toLowerCase() === 'custom');
+
+const escapeTitle = (value) => value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+function titleTextOf(node) {
+  let out = '';
+  const walk = (current) => {
+    for (const child of current.childNodes ?? []) {
+      if (child.nodeName === '#text') out += child.value;
+      else walk(child);
+    }
+  };
+  if (node) walk(node);
+  return out;
+}
+
+// A title with no element of its own goes after the head's start tag, else before its
+// first child, else before the body starts.
+function titleAt(placement) {
+  const head = placement.head?.sourceCodeLocation;
+  if (head?.startTag) return head.startTag.endOffset;
+  const inside = (placement.head?.childNodes ?? []).find((node) => node.sourceCodeLocation);
+  if (inside) return inside.sourceCodeLocation.startOffset;
+  const body = placement.body?.sourceCodeLocation;
+  if (body?.startTag) return body.startTag.startOffset;
+  const first = (placement.body?.childNodes ?? []).find((node) => node.sourceCodeLocation);
+  return first ? first.sourceCodeLocation.startOffset : null;
+}
+
+function titleEdit(placement, title) {
+  if (placement.title) {
+    const loc = placement.title.sourceCodeLocation;
+    if (!loc?.startTag || !loc.endTag) return null;
+    return { start: loc.startTag.endOffset, end: loc.endTag.startOffset, text: escapeTitle(title) };
+  }
+  const at = titleAt(placement);
+  return at === null ? null : { start: at, end: at, text: `<title>${escapeTitle(title)}</title>` };
+}
+
 // Whether the room's blocks already carry everything the hand-edited article
 // changed since its tag was written: merging those changes in changes nothing.
 function holdsEdit(found, blocks, doc) {
@@ -151,6 +203,11 @@ function adoptionNeeded(html, createDocument) {
   }
 }
 
+// An article that carries a semantic envelope holds content this renderer cannot
+// project from the room's blocks. Rewriting it would drop that content, so the
+// checkpoint refuses instead, leaving the file as it stands.
+const holdsEnvelope = (html) => html.includes(`${OPAQUE}="`) || html.includes(`${MARKS}="`);
+
 // recovery: render the room's blocks even over an article it has not merged, for
 // a recovered copy of its edits (the file itself keeps the outside edit).
 export function renderCheckpoint(currentHtml, capture, { createDocument, recovery = false }) {
@@ -175,7 +232,9 @@ export function renderCheckpoint(currentHtml, capture, { createDocument, recover
     // A tab that merged this article says so on the frame that carried the
     // merge; otherwise the blocks must show the edit.
     if (!recovery && found.kind === 'adopt' && capture.adopted !== found.A && !holdsEdit(found, decoded.blocks, doc)) return { kind: 'refused', reason: 'needs-adoption' };
+    const current = currentHtml.slice(articleLoc.startTag.endOffset, articleLoc.endTag.startOffset);
     rendered = renderBlocks(decoded.blocks, { clean: fragmentCleaner(doc) });
+    if (current !== rendered.html && holdsEnvelope(current)) return { kind: 'refused', reason: 'unknown-page-content' };
   }
   catch (error) {
     if (error instanceof YDecodeError || error instanceof SyntaxError) return { kind: 'refused', reason: 'invalid-document' };
@@ -196,6 +255,10 @@ export function renderCheckpoint(currentHtml, capture, { createDocument, recover
     articleOpen.slice(revLoc.endOffset - articleLoc.startTag.startOffset) : articleOpen;
   edits.push({ start: articleLoc.startTag.startOffset, end: articleLoc.startTag.endOffset, text: articleStart.slice(0, -1) + rev + '>' });
   edits.push({ start: articleLoc.startTag.endOffset, end: articleLoc.endTag.startOffset, text: rendered.html });
+  if (!customTitleOf(placement.titleModes)) {
+    const edit = titleEdit(placement, documentTitle(rendered.model));
+    if (edit) edits.push(edit);
+  }
   return { kind: 'ok', html: replace(currentHtml, edits), revision: rendered.rev };
 }
 
@@ -208,6 +271,7 @@ export function isCheckpointCurrent(currentHtml, capture) {
   const articleLoc = placement.article.sourceCodeLocation;
   if (attr(placement.article, 'data-rev') !== rendered.rev ||
     currentHtml.slice(articleLoc.startTag.endOffset, articleLoc.endTag.startOffset) !== rendered.html) return false;
+  if (!customTitleOf(placement.titleModes) && titleTextOf(placement.title) !== documentTitle(rendered.model)) return false;
   return capture.stores.every((store) => {
     const node = placement.tags.get(store.name);
     const loc = node.sourceCodeLocation;

package/src/server/offline-runtime/index.js

@@ -0,0 +1,214 @@
+import { parse } from "../../vendor/parse5.vendor.js";
+import {
+  canonicalizeRuntimeURL,
+  parseRuntimeURL,
+  resolveRuntimeURL,
+} from "../../lib/offline-runtime.js";
+
+export { canonicalizeRuntimeURL, parseRuntimeURL, resolveRuntimeURL };
+
+export const DESCRIPTOR_ID = "clay-runtime-map";
+
+const RUNTIME_REL = new Set(["stylesheet", "preload", "modulepreload"]);
+
+function attributeOf(node, name) {
+  for (const attr of node.attrs ?? []) {
+    if (attr.name === name) return attr;
+  }
+  return null;
+}
+
+function isCandidate(node) {
+  if (node.tagName === "script") return Boolean(attributeOf(node, "src"));
+  if (node.tagName !== "link") return false;
+  if (!attributeOf(node, "href")) return false;
+  const rel = String(attributeOf(node, "rel")?.value ?? "").toLowerCase();
+  return rel.split(/\s+/).some((token) => RUNTIME_REL.has(token));
+}
+
+function valueBounds(raw) {
+  const eq = raw.indexOf("=");
+  if (eq < 0) return null;
+  let index = eq + 1;
+  while (index < raw.length && /\s/.test(raw[index])) index += 1;
+  const quote = raw[index] === '"' || raw[index] === "'" ? raw[index] : "";
+  if (!quote) return { start: index, end: raw.length, quote };
+  const close = raw.lastIndexOf(quote);
+  return { start: index + 1, end: close > index ? close : raw.length, quote };
+}
+
+function elements(doc) {
+  const found = [];
+  const walk = (node) => {
+    if (node.tagName) found.push(node);
+    for (const child of node.childNodes ?? []) walk(child);
+    if (node.content) walk(node.content);
+  };
+  walk(doc);
+  return found;
+}
+
+function candidates(doc, html) {
+  const found = [];
+  for (const node of elements(doc)) {
+    if (!isCandidate(node)) continue;
+    const name = node.tagName === "script" ? "src" : "href";
+    const location = node.sourceCodeLocation?.attrs?.[name];
+    if (!location) continue;
+    const bounds = valueBounds(html.slice(location.startOffset, location.endOffset));
+    if (!bounds) continue;
+    found.push({
+      node,
+      value: attributeOf(node, name).value,
+      raw: html.slice(location.startOffset + bounds.start, location.startOffset + bounds.end),
+      valueStart: location.startOffset + bounds.start,
+      valueEnd: location.startOffset + bounds.end,
+      startOffset: node.sourceCodeLocation.startTag?.startOffset ?? node.sourceCodeLocation.startOffset,
+      quote: bounds.quote,
+    });
+  }
+  return found;
+}
+
+function applySplices(html, splices) {
+  const ordered = [...splices].sort((a, b) => b.start - a.start);
+  let out = html;
+  for (const splice of ordered) {
+    out = out.slice(0, splice.start) + splice.text + out.slice(splice.end);
+  }
+  return out;
+}
+
+function attributeText(value, quote) {
+  const text = value.replace(/&/g, "&amp;");
+  if (quote === "'") return text.replace(/'/g, "&#39;");
+  if (quote === '"') return text.replace(/"/g, "&quot;");
+  return /[\s"'<>=`]/.test(text) ? `"${text.replace(/"/g, "&quot;")}"` : text;
+}
+
+// The attribute text for `replacement`, keeping the file's own spelling of the tail it shares with
+// `value`, so a query written with a bare `&` keeps it. `raw` is how `value` is written in the file.
+// A shared head that holds `&` could split a character reference, so that case escapes everything.
+function respelled(raw, value, replacement, quote) {
+  let shared = 0;
+  while (
+    shared < value.length &&
+    shared < replacement.length &&
+    value[value.length - 1 - shared] === replacement[replacement.length - 1 - shared]
+  ) shared += 1;
+  const head = value.slice(0, value.length - shared);
+  const newHead = replacement.slice(0, replacement.length - shared);
+  if (head.includes("&") || !raw.startsWith(head)) return attributeText(replacement, quote);
+  if (!quote && /[\s"'<>=`]/.test(newHead)) return attributeText(replacement, quote);
+  return attributeText(newHead, quote) + raw.slice(head.length);
+}
+
+function descriptorTag(version, entries) {
+  const descriptor = { schema: 1, version, entries };
+  const json = JSON.stringify(descriptor).replace(/</g, "\\u003c");
+  return `<script type="application/json" id="${DESCRIPTOR_ID}" clay="no-save no-watch no-snapshot">${json}</script>`;
+}
+
+export function projectRuntimeHTML(html, { releases, selectedVersion, documentURL, descriptor = true } = {}) {
+  const nodes = candidates(parse(html, { sourceCodeLocationInfo: true }), html);
+  const resolved = nodes.map((node) => ({
+    node,
+    result: resolveRuntimeURL(node.value, { releases, selectedVersion, documentURL }),
+  }));
+
+  const versions = new Set();
+  let missing = false;
+  let absent = false;
+  for (const { node, result } of resolved) {
+    if (!result) {
+      const parsed = parseRuntimeURL(node.value, { documentURL });
+      if (parsed && (parsed.kind === "rolling" || parsed.kind === "exact")) absent = true;
+      continue;
+    }
+    if (result.available === false) missing = true;
+    versions.add(result.version);
+  }
+  if (missing || absent || versions.size > 1) {
+    return {
+      html,
+      mappings: [],
+      skipped: [],
+      unavailable: {
+        reason: missing ? "release-missing" : absent ? "path-missing" : "mixed-versions",
+        versions: [...versions].sort(),
+      },
+    };
+  }
+
+  const mappings = [];
+  const splices = [];
+  const version = versions.size === 1 ? [...versions][0] : null;
+  let insertAt = null;
+
+  for (const { node, result } of resolved) {
+    if (!result) continue;
+    splices.push({
+      start: node.valueStart,
+      end: node.valueEnd,
+      text: respelled(node.raw, node.value, result.localURL, node.quote),
+    });
+    mappings.push({ original: node.value, local: result.localURL });
+    if (insertAt === null) insertAt = node.startOffset;
+  }
+
+  if (!mappings.length) return { html, mappings, skipped: [], unavailable: null };
+
+  if (descriptor) splices.push({ start: insertAt, end: insertAt, text: descriptorTag(version, mappings) });
+  return { html: applySplices(html, splices), mappings, skipped: [], unavailable: null };
+}
+
+function descriptorSpan(node) {
+  const location = node.sourceCodeLocation;
+  if (!location) return null;
+  const start = location.startTag?.startOffset ?? location.startOffset;
+  const end = location.endTag ? location.endTag.endOffset : location.endOffset;
+  return { start, end };
+}
+
+function descriptorText(html, node) {
+  const location = node.sourceCodeLocation;
+  if (!location) return "";
+  const start = location.startTag?.endOffset ?? location.startOffset;
+  const end = location.endTag ? location.endTag.startOffset : location.endOffset;
+  return html.slice(start, end);
+}
+
+export function canonicalizeRuntimeHTML(html, { releases, documentURL } = {}) {
+  const doc = parse(html, { sourceCodeLocationInfo: true });
+  const nodes = candidates(doc, html);
+  const splices = [];
+  let descriptor = null;
+  let descriptorRemoved = false;
+
+  for (const node of elements(doc)) {
+    if (node.tagName !== "script" || attributeOf(node, "id")?.value !== DESCRIPTOR_ID) continue;
+    const span = descriptorSpan(node);
+    if (!span) continue;
+    if (!descriptorRemoved) {
+      try {
+        descriptor = JSON.parse(descriptorText(html, node));
+      } catch {
+        descriptor = null;
+      }
+    }
+    descriptorRemoved = true;
+    splices.push({ start: span.start, end: span.end, text: "" });
+  }
+
+  let changed = 0;
+  for (const node of nodes) {
+    const parsed = parseRuntimeURL(node.value, { documentURL });
+    if (!parsed || parsed.kind !== "local") continue;
+    const replacement = canonicalizeRuntimeURL(node.value, { descriptor, releases, documentURL });
+    if (replacement === node.value) continue;
+    splices.push({ start: node.valueStart, end: node.valueEnd, text: respelled(node.raw, node.value, replacement, node.quote) });
+    changed += 1;
+  }
+
+  return { html: applySplices(html, splices), changed, descriptorRemoved };
+}

package/src/server/rooms/index.js

@@ -40,7 +40,8 @@ export {
   postReceipt,
 } from './live-provenance.js';
 
-export { isHybridPageValue, isYPageValue, inspectPage, pageBaseline } from './page-admission.js';
+export { isHybridPageValue, isYPageValue, inspectPage, pageBaseline, captureFormat, checkPageFormatAdmission } from './page-admission.js';
+export { PAGE_FORMAT, PAGE_FORMAT_HEADER, PAGE_FORMAT_EXTENSION, PAGE_FORMAT_UPGRADE, formatCapability, pageFormatFloor, withPageFormatFloor } from '../../core/page-format.js';
 
 export { splitPage, composePage, pageRev } from './page-state.js';
 

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

@@ -422,9 +422,9 @@ export function createRooms({ now = Date.now, newEpoch = randomUUID, liveBytes =
       return reservePageTarget(key, nodeId, room, html, { source, base, epoch, names, format: 'yjs' });
     },
 
-    reservePageInitial(key, { nodeId, currentHtml, html, ifMatch }) {
+    reservePageInitial(key, { nodeId, currentHtml, html, ifMatch, pageWrite = null, createDocument }) {
       const room = pageSource(key, nodeId);
-      checkPageInitial({ currentHtml, html, ifMatch, room });
+      checkPageInitial({ currentHtml, html, ifMatch, room, pageWrite, createDocument });
       return reservePageTarget(key, nodeId, room, html, { source: 'initial', names: [], format: 'yjs' });
     },
 

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

@@ -3,6 +3,9 @@ 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';
+import { project } from '../../page/projection.js';
+import { blocksFromPageValues } from '../../page/ybind/decode.js';
+import { pageFormatDecision, pageFormatFloor, pageFormatRefusal, requiredPageFormat, withPageFormatFloor } from '../../page/format-level.js';
 
 const PAGE = /^page(\.[0-9]+)?$/;
 const PART = /^(.+)\.(\d+)\.(\d+)$/;
@@ -77,3 +80,33 @@ export function pageBaseline(tags) {
   });
   return createHash('sha256').update(canon(source), 'utf8').digest('hex');
 }
+
+// The floor a prospective page value needs: 1 when the model the capture would
+// store holds a newer runtime's mark, block or field, 0 when it holds only what
+// the frozen floor-0 registry knows. Invalid content refuses here rather than
+// answering with a level, so a malformed capture cannot buy admission.
+export function captureFormat(html) {
+  const answer = inspectPage(html ?? '');
+  if (answer.kind !== 'yjs') return 0;
+  return requiredPageFormat(project(blocksFromPageValues([answer.tags[0][1]])));
+}
+
+// The floor decision for one page write, taken before anything is mutated.
+// `floor` is the document's established floor, `required` what the captured
+// content needs (its own marker included) and `capability` what the writer
+// declares in X-Clay-Page-Format. `admitted` lists the capabilities of the page
+// editors the room has admitted, so a floor rise is refused while an editor that
+// could not read the result is connected. On success the returned body carries
+// the marker the room must persist, so a stale save that omitted it cannot lower
+// the floor.
+export function checkPageFormatAdmission({ currentHtml, html, capability = 0, admitted = [] }) {
+  const established = pageFormatFloor(currentHtml ?? '');
+  const decision = pageFormatDecision({
+    floor: established,
+    required: Math.max(captureFormat(html), pageFormatFloor(html ?? '')),
+    capability,
+    admitted,
+  });
+  if (!decision.ok) throw pageFormatRefusal(decision.minimum);
+  return { ...decision, html: withPageFormatFloor(html, decision.floor) };
+}