@panphora/clayjs 1.15.2 → 1.17.0

package/src/core/runtime-url.js

@@ -0,0 +1,105 @@
+import { setCloneCanonicalizer } from "./snapshot.js";
+import {
+  LOCAL_PREFIX,
+  canonicalizeRuntimeURL,
+  parseRuntimeURL,
+} from "../lib/offline-runtime.js";
+
+// The release's exact aliases, from compat/journal-assets.lock.json: the only foreign URLs a
+// saved page may get back for a local runtime address. A unit test keeps the two equal.
+export const RUNTIME_ALIASES = Object.freeze({
+  "https://cdn.jsdelivr.net/npm/overtype@2.6.1/dist/overtype.min.js": "compat/overtype-2.6.1.min.js",
+  "https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js": "compat/highlight-11.9.0.min.js",
+  "https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:ital,wght@0,300;0,400;0,500;0,600;1,400;1,500&family=IBM+Plex+Sans:wght@400;500;600&display=swap": "fonts/ibm-plex.css",
+});
+
+export const RUNTIME_MAP_ID = "clay-runtime-map";
+
+const RUNTIME_REL = new Set(["stylesheet", "preload", "modulepreload"]);
+
+let cachedText = null;
+let cachedDescriptor = null;
+
+function parseDescriptor(text) {
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!value || typeof value !== "object" || value.schema !== 1) return null;
+  return value;
+}
+
+export function runtimeDescriptor() {
+  if (typeof document === "undefined") return null;
+  const element = document.getElementById(RUNTIME_MAP_ID);
+  if (!element) return null;
+  const text = element.textContent ?? "";
+  if (text === cachedText) return cachedDescriptor;
+  cachedText = text;
+  cachedDescriptor = parseDescriptor(text);
+  return cachedDescriptor;
+}
+
+const RUNTIME_SELECTOR = `script[src*="${LOCAL_PREFIX}"], link[href*="${LOCAL_PREFIX}"], #${RUNTIME_MAP_ID}`;
+
+// Native selector first: this runs on every capture, dirty checks included, and almost every page
+// has nothing to canonicalize.
+function holdsRuntime(root) {
+  if (root.querySelector(RUNTIME_SELECTOR)) return true;
+  for (const template of root.querySelectorAll("template")) {
+    if (holdsRuntime(template.content)) return true;
+  }
+  return false;
+}
+
+function elements(root) {
+  const found = [];
+  const stack = [root];
+  while (stack.length) {
+    const node = stack.pop();
+    for (const child of node.children ?? []) {
+      found.push(child);
+      stack.push(child);
+      if (child.content) stack.push(child.content);
+    }
+  }
+  return found;
+}
+
+function candidateAttribute(element) {
+  if (element.tagName === "SCRIPT" && element.hasAttribute("src")) return "src";
+  if (element.tagName !== "LINK" || !element.hasAttribute("href")) return null;
+  const rel = (element.getAttribute("rel") ?? "").toLowerCase();
+  return rel.split(/\s+/).some((token) => RUNTIME_REL.has(token)) ? "href" : null;
+}
+
+export function canonicalizeRuntimeClone(clone) {
+  if (!clone || !holdsRuntime(clone)) return;
+
+  const candidates = [];
+  let runtime = false;
+  for (const element of elements(clone)) {
+    if (element.getAttribute("id") === RUNTIME_MAP_ID) {
+      element.remove();
+      continue;
+    }
+    const name = candidateAttribute(element);
+    if (!name) continue;
+    candidates.push({ element, name });
+    if (!runtime && (element.getAttribute(name) ?? "").includes(LOCAL_PREFIX)) runtime = true;
+  }
+  if (!runtime) return;
+
+  const documentURL = location.href;
+  const descriptor = runtimeDescriptor();
+  for (const { element, name } of candidates) {
+    const value = element.getAttribute(name);
+    const parsed = parseRuntimeURL(value, { documentURL });
+    if (!parsed || parsed.kind !== "local") continue;
+    element.setAttribute(name, canonicalizeRuntimeURL(value, { descriptor, documentURL, aliases: RUNTIME_ALIASES }));
+  }
+}
+
+setCloneCanonicalizer(canonicalizeRuntimeClone);

package/src/core/save-core.js

@@ -13,11 +13,16 @@ import { consumeUserDriven, consumeExplicitSave, markUserDriven } from "../lib/u
 import { saveToken } from "./host-attrs.js";
 import { lastSeenEtag, conditionalSaves, recordEtag } from "./etag.js";
 import { hostMeta } from "./host-meta.js";
+import { saveSize, storedFile, knownSaveLimit, saveLimit, announceSaveSize } from "./save-size.js";
+import { PAGE_FORMAT, PAGE_FORMAT_HEADER, knownPageFormatFloor, withPageFormatFloor } from "./page-format.js";
+import "./runtime-url.js";
 import {
   getPageContents,
   onSnapshot,
   addDocumentTransform,
-  currentCaptureId
+  currentCaptureId,
+  captureArtifact,
+  releaseCaptureArtifact
 } from "./snapshot.js";
 
 // =============================================================================
@@ -100,10 +105,16 @@ export function onSaveAccepted(callback) {
   saveAcceptedHooks.push(callback);
 }
 
-function notifySaveAccepted(html, captureId) {
+function notifySaveAccepted(html, captureId, artifact = null) {
   for (const hook of saveAcceptedHooks) {
     try {
-      hook(html, { captureId: captureId ?? null });
+      // The artifact is the capture's own private model of these bytes, and it is
+      // offered only when it exists: a raw save and a capture without one keep the
+      // shape they had.
+      const accepted = artifact
+        ? { captureId: captureId ?? null, artifact }
+        : { captureId: captureId ?? null };
+      hook(html, accepted);
     } catch (err) {
       console.error('clayjs: onSaveAccepted hook failed:', err);
     }
@@ -242,7 +253,7 @@ export function saveFateIsUnknown() {
  * zeroed array is the failure that would do exactly that, silently, so a missing
  * crypto implementation falls back to something random rather than to zeros.
  */
-function mintSaveId() {
+export function mintSaveId() {
   const uuid = window.crypto?.randomUUID?.();
   if (uuid) return uuid;
   if (window.crypto?.getRandomValues) {
@@ -339,6 +350,49 @@ function skippedResult(msg) {
   return { ok: false, msg, msgType: 'skipped', code: null, etag: null };
 }
 
+// A body the host will not store, refused here instead of on the wire. It is an
+// ordinary error result with one more fact on it, because the caller's answer to
+// "too large" is the same answer it gives any failed save: keep the writing, do not
+// mark it saved, and let the person shrink or download it.
+function tooLargeResult(size) {
+  const err = new Error(`This document is ${size.bytes} bytes; this host saves at most ${size.maxBytes}`);
+  err.code = 'save-too-large';
+  return { ...errorResult(err), sent: false, size };
+}
+
+// ============================================
+// THE DOCUMENT-OPERATION SLOT
+// ============================================
+//
+// One slot for the operations that speak for the document as a whole: a mode switch's
+// barrier, an upgrade, and a whole-document replacement. Two of them at once is how a
+// generation gets flushed and then replaced by a later one, so the second asks and is
+// told no instead of interleaving. Kinds are open strings; the slot only cares that it
+// is exclusive, and that the token it hands back is the one that releases it.
+let documentOperation = null;
+
+/**
+ * Take the slot, or learn it is taken.
+ *
+ * @param {string} kind - 'mode' | 'replace' | 'upgrade'
+ * @returns {?Object} an opaque token to release with, or null when an operation holds it
+ */
+export function claimDocumentOperation(kind) {
+  if (documentOperation) return null;
+  documentOperation = { kind };
+  return documentOperation;
+}
+
+/** Release the slot. Only the token that holds it does anything; idempotent. */
+export function releaseDocumentOperation(token) {
+  if (documentOperation === token) documentOperation = null;
+}
+
+/** Which operation holds the document, or null. */
+export function operationKind() {
+  return documentOperation ? documentOperation.kind : null;
+}
+
 // The metadata a caller attaches to a capture was refused here, before anything
 // went out. The host's own grammar is the only definition of valid, so an
 // `invalid-header` here is the same answer a host would have given, without the
@@ -437,7 +491,7 @@ function formatConversionHeader(conversion) {
  * @param {?string} conversionHeader - the `Page-Conversion` value for this logical save, or null
  * @returns {{url: string, options: Object}}
  */
-function buildSaveRequest(content, userDriven, signal, saveId, etag, keepalive = false, conversionHeader = null) {
+export function buildSaveRequest(content, userDriven, signal, saveId, etag, keepalive = false, conversionHeader = null) {
   const token = saveToken();
   const path = token ? `${SAVE_PATH}/${token}` : SAVE_PATH;
   const options = {
@@ -457,7 +511,11 @@ function buildSaveRequest(content, userDriven, signal, saveId, etag, keepalive =
       // gating it on discovery would mean holding the save until an async lookup
       // resolved. Nothing is inferred from the header being accepted: only a host
       // that ANSWERS with the id has said anything.
-      'Save-ID': saveId
+      'Save-ID': saveId,
+      // The page format this client writes. R understands floor 1 and says so on
+      // every page save; a host reads it as protocol capability, never as
+      // authorization, and refuses a lower one before mutation.
+      [PAGE_FORMAT_HEADER]: String(PAGE_FORMAT)
     },
     body: content
   };
@@ -595,7 +653,11 @@ function sendOnce(content, saveId, etag, { captureId = null, conversionHeader =
       }
       if (!res.ok) {
         const error = new Error(data.msg || data.error || `HTTP ${res.status}: ${res.statusText}`);
-        error.code = data.code ?? null;
+        // A 413 is the host refusing these bytes for their size, whatever it called
+        // the refusal: the one code a caller can act on is the same one the local
+        // guard gives. No limit is invented from it — a refusal is not an
+        // announcement, and the measurement the caller sees is this attempt's own.
+        error.code = res.status === 413 ? 'save-too-large' : (data.code ?? null);
         error.status = res.status;
         // Spec §6: a conflict may name what moved the document. Only the host can
         // know, and it often cannot, so this rides through as-is and the notice
@@ -819,11 +881,25 @@ async function sendSave(content, { captureId = null, conversionHeader = null, at
 // One private implementation behind every entry point, so the hooks see the same
 // thing whether the bytes came from a bound capture or a raw caller. `captureId`
 // is null for a raw save: it belongs to no capture and can confirm none.
-function runSave(html, captureId, callback, conversion) {
+//
+// `pageFormatFloor` is internal: one save may carry a floor this tab has not
+// noted yet, which is how the format gate's activation writes the marker. It
+// raises these bytes only, never what the tab knows the document at.
+function runSave(html, captureId, callback, conversion, capture = null, pageFormatFloor = 0) {
+  // A capture taken before the floor rose cannot drop the marker by omitting it:
+  // the bytes that go out carry the floor this tab last saw. At floor 0 this is
+  // the string itself, unchanged.
+  html = withPageFormatFloor(html, Math.max(knownPageFormatFloor(), pageFormatFloor));
   return new Promise((resolve) => {
     const attempts = [];
+    // Read once, before the first request: the artifact belongs to the capture that
+    // produced these bytes, and it is released however this save settles. A timeout
+    // recovered through the host's receipt reaches `accepted` like any other success,
+    // so it adopts the artifact of the request that landed.
+    const artifact = captureArtifact(capture);
     const finished = (result, accepted = false) => {
-      if (accepted) notifySaveAccepted(html, captureId ?? null);
+      if (accepted) notifySaveAccepted(html, captureId ?? null, artifact);
+      releaseCaptureArtifact(capture);
       notifySaveOutcome({
         captureId: captureId ?? null,
         result,
@@ -859,6 +935,20 @@ function runSave(html, captureId, callback, conversion) {
       return;
     }
 
+    // The one measurement every entry point shares: the exact string about to be
+    // handed to the backend, once per attempt, whichever lane asked. Not a second
+    // capture — these are the bytes 05b already took — and not `outerHTML`, which is
+    // a different string. The limit is whatever discovery last said; unknown refuses
+    // nothing, so a host that advertises no ceiling, or has not answered yet, gets the
+    // save and stays the authority on it.
+    saveLimit();
+    const size = saveSize(storedFile(html), knownSaveLimit());
+    announceSaveSize(size);
+    if (size.state === 'over') {
+      saveInProgress = false;
+      return finished(tooLargeResult(size));
+    }
+
     sendSave(html, { captureId, conversionHeader: formatted.header, attempts })
       .then(successResult, errorResult)
       // Clear the flag BEFORE handing the result back, so a caller that queues a
@@ -866,7 +956,11 @@ function runSave(html, captureId, callback, conversion) {
       // is busy by the save that just finished.
       .then(result => {
         saveInProgress = false;
-        if (result.ok) notifySaveAccepted(html, captureId ?? null);
+        // A host's 413 is the same refusal the guard above makes, so it carries the
+        // same measurement. Its own answer about the size wins over nothing: the bytes
+        // are this attempt's, and the limit is still only what discovery advertised.
+        if (result.code === 'save-too-large' && !result.size) result.size = size;
+        if (result.ok) notifySaveAccepted(html, captureId ?? null, artifact);
         finished(result);
       });
   });
@@ -904,8 +998,8 @@ export function saveHtml(html, callback = () => {}) {
  * @param {Object} [options.conversion] - {source:'file', base} or {source:'room', base, epoch}
  * @returns {Promise<Object>}
  */
-export function saveCapturedHtml(html, captureId, callback = () => {}, { conversion } = {}) {
-  return runSave(html, captureId, callback, conversion);
+export function saveCapturedHtml(html, captureId, callback = () => {}, { conversion, capture = null, pageFormatFloor } = {}) {
+  return runSave(html, captureId, callback, conversion, capture, pageFormatFloor);
 }
 
 /**
@@ -936,15 +1030,22 @@ export function saveConversion({ html, captureId, conversion }) {
  */
 export function replacePageWith(url, callback = () => {}) {
   return new Promise((resolve) => {
+    let operation = null;
     const done = (result) => {
+      releaseDocumentOperation(operation);
       if (typeof callback === 'function') callback(result);
       resolve(result);
     };
 
     if (!isEditMode) return done(skippedResult('Not in edit mode'));
+    if (operationKind()) return done(skippedResult('Another document operation is in progress'));
     if (saveInProgress) return done(skippedResult('Save already in progress'));
     if (isDraftMode) return done(false);
 
+    // A replacement writes the whole document, so it holds the slot from the fetch to
+    // the save: a mode switch cannot start its barrier in the middle of one.
+    operation = claimDocumentOperation('replace');
+
     // Resolved against the document's real location, not a <base href> the page
     // may have set.
     fetch(new URL(url, window.location.href).href)

package/src/core/save-replace.js

@@ -0,0 +1,72 @@
+// One conditional save of bytes this page did not build: the upgrade path's write
+// (plan 05, Step 6). It is deliberately not part of the save core every editor
+// loads. There is no capture, no beforeSave, no snapshot and no retry: the bytes
+// handed in are the whole document, already composed by the caller, and the only
+// question this answers is whether the host took them.
+//
+// It speaks through the same request builder as every other save, so the endpoint,
+// the headers and the token route are the save lane's own. `If-Match` comes from the
+// caller (the stamp the page was loaded with or last saved at) and falls back to the
+// tab's stamp. A host that did not announce `conditional` gets no request at all:
+// without the capability the header means nothing, and a write this large is not
+// worth sending to a host that cannot refuse it.
+import { buildSaveRequest, mintSaveId } from "./save-core.js";
+import { conditionalSaves, lastSeenEtag, recordEtag, seedEtag } from "./etag.js";
+
+const TIMEOUT_MS = 30000;
+
+function failed() {
+  return { ok: false, code: "failed" };
+}
+
+/**
+ * Save exactly `html` over the document, conditional on the version it replaces.
+ *
+ * @param {string} html - the whole document, as it should be stored
+ * @param {Object} [options]
+ * @param {?string} [options.etag] - the stamp to replace, defaulting to this tab's
+ * @returns {Promise<{ok: true, etag: ?string}|{ok: false, code: "conflict"|"forbidden"|"unsupported"|"failed"}>}
+ */
+export async function replace(html, { etag } = {}) {
+  if (typeof html !== "string" || html === "") return failed();
+
+  const given = typeof etag === "string" && etag ? etag : null;
+  // Discovery is what says whether the capability exists, and it is also where a
+  // tab that has never saved learns the stamp it is about to replace.
+  if (!conditionalSaves()) await seedEtag();
+  if (!conditionalSaves()) return { ok: false, code: "unsupported" };
+
+  // With no stamp the write would be unconditional, which is exactly what this lane
+  // promises never to send. A reload gives the tab the stamp it is missing.
+  const stamp = given || lastSeenEtag();
+  if (!stamp) return { ok: false, code: "conflict" };
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  try {
+    const { url, options } = buildSaveRequest(html, true, controller.signal, mintSaveId(), stamp);
+    const res = await fetch(url, options);
+    const text = await res.text();
+    let data = {};
+    if (text) {
+      try {
+        data = JSON.parse(text);
+      } catch (_) {
+        data = {};
+      }
+    }
+    if (!res.ok) {
+      if (res.status === 412) return { ok: false, code: "conflict" };
+      if (res.status === 401 || res.status === 403) return { ok: false, code: "forbidden" };
+      return failed();
+    }
+    const stored = typeof data.etag === "string" && data.etag ? data.etag : null;
+    // The write landed, so the stamp it replaced describes bytes the host no longer
+    // stores: the answer's own stamp is the one this tab holds from here on.
+    recordEtag(stored);
+    return { ok: true, etag: stored };
+  } catch (_) {
+    return failed();
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}

package/src/core/save-size-notice.js

@@ -0,0 +1,134 @@
+import { isEditMode } from "./is-edit-mode.js";
+import { downloadStored } from "./conflict-download.js";
+import { bevelSurface, bevelText, bevelButton, pageScheme, setShown } from "../ui/bevel-controls.js";
+import { set } from "../lib/hostile-css.js";
+
+// The one quiet word about how large this document is.
+//
+// `clay:save-size` is a measurement of a real save attempt, never a live reading, so
+// every sentence here says "At the last save attempt": the number is the bytes the last
+// attempt measured, and nothing claims the page is that size now. Most documents never
+// reach the host's advertised limit, so save.js fetches this module only when one does,
+// and it draws nothing until then.
+//
+// One element, updated in place: a save on a phone fires often, and a notice per save
+// would be a toast storm. A later measurement below the near threshold takes it away,
+// and so does leaving edit: the notice is editor chrome, not part of the page.
+//
+// The download is the safe copy this library already offers for the current document
+// (conflict-download.js's `downloadStored`), a file openable in a browser rather than a
+// save the host would refuse.
+
+const NEAR_MESSAGE = "Download a copy, then reduce its size; saving still works.";
+const OVER_MESSAGE = "Download a copy to keep your work.";
+
+let root = null;
+let sentence = null;
+let copy = null;
+let listeners = null;
+
+// A size a person can read at a glance. Kilobyte precision under a megabyte, one
+// decimal above it: the question is "how close is this to the limit", not the exact byte.
+function readable(bytes) {
+  if (typeof bytes !== "number" || !Number.isFinite(bytes) || bytes < 0) return "an unknown size";
+  if (bytes >= 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  if (bytes >= 1024) return `${Math.max(1, Math.round(bytes / 1024))} KB`;
+  return `${bytes} bytes`;
+}
+
+function words({ bytes, maxBytes, state }) {
+  const measured = `At the last save attempt: ${readable(bytes)} of ${readable(maxBytes)}.`;
+  return state === "over"
+    ? `This host can't save a file this size. ${measured} ${OVER_MESSAGE}`
+    : `This file is getting large. ${measured} ${NEAR_MESSAGE}`;
+}
+
+// A phone keyboard shrinks the visual viewport but leaves fixed elements pinned to the
+// layout viewport, so a bottom-anchored bar parks itself behind the keyboard. Same fix
+// as the conflict notice.
+function place() {
+  if (!root) return;
+  const vv = window.visualViewport;
+  const lift = vv ? Math.max(0, window.innerHeight - vv.height - vv.offsetTop) : 0;
+  set(root, "bottom", `calc(${16 + lift}px + env(safe-area-inset-bottom,0px))`);
+}
+
+// The safe copy the conflict notice offers, for the same reason: a file the person can
+// open has to exist outside a host that will not store these bytes. It already reports
+// its own failure.
+function download() {
+  downloadStored({});
+}
+
+function build() {
+  root = bevelSurface("div", [
+    "position:fixed", "left:50%", "transform:translateX(-50%)",
+    "z-index:2147483000", "display:flex", "align-items:center", "gap:10px 12px",
+    "width:max-content", "max-width:calc(100vw - 24px)", "flex-wrap:wrap",
+    "padding:8px 8px 8px 14px", "text-align:left", `color-scheme:${pageScheme()}`,
+  ]);
+  // An injected element is in no document on disk, and `editor-ui` is the bundle that
+  // says so: not saved, not watched, not in any snapshot, not undoable, not data. The
+  // controls inside carry the same markers, as every other notice this library draws.
+  root.setAttribute("clay", "editor-ui");
+  root.setAttribute("data-clay-save-size", "");
+  root.setAttribute("role", "status");
+  sentence = bevelText("span", [], "");
+  copy = bevelButton("Download my copy", { small: true, onClick: download });
+  setShown(copy, false, "inline-flex");
+  root.append(sentence, copy);
+  document.body.appendChild(root);
+  place();
+  window.visualViewport?.addEventListener("resize", place);
+  window.visualViewport?.addEventListener("scroll", place);
+}
+
+function render(size) {
+  if (!root) build();
+  sentence.textContent = words(size);
+  // Only an oversize document offers the copy: a near one still saves, and its text
+  // already recommends downloading one.
+  setShown(copy, size.state === "over", "inline-flex");
+  place();
+}
+
+function clear() {
+  if (!root) return;
+  window.visualViewport?.removeEventListener("resize", place);
+  window.visualViewport?.removeEventListener("scroll", place);
+  root.remove();
+  root = null;
+  sentence = null;
+  copy = null;
+}
+
+function onSaveSize(event) {
+  const size = event?.detail;
+  if (!size) return;
+  if (size.state === "near" || size.state === "over") render(size);
+  else clear();
+}
+
+function onModeChange() {
+  if (!isEditMode) stop();
+}
+
+// announceSaveSize (save-size.js) asks for this file on the first measurement that is near or over,
+// and hands it the event that asked: it is replayed here, after the listeners are on,
+// exactly as if it had arrived on a page that already held the notice.
+export function start(trigger) {
+  if (!isEditMode) return;
+  listeners ||= new AbortController();
+  document.addEventListener("clay:save-size", onSaveSize, { signal: listeners.signal });
+  document.addEventListener("clay:modechange", onModeChange, { signal: listeners.signal });
+  if (trigger?.type === "clay:save-size") onSaveSize(trigger);
+}
+
+// A committed exit takes the notice with it: the handlers, the node it drew and the
+// measurement it was drawing. A later entry starts again from whatever the next save
+// measures.
+export function stop() {
+  listeners?.abort();
+  listeners = null;
+  clear();
+}

package/src/core/save-size.js

@@ -0,0 +1,140 @@
+/**
+ * save-size.js — how large a save's exact bytes are, and the host's own ceiling (§9).
+ *
+ * `document.maxBytes` in discovery is the one place a host states what it will store:
+ * the maximum uncompressed UTF-8 size of the HTML save body, inclusive. Only a
+ * positive safe integer is an answer; missing, zero, negative, fractional and
+ * nonnumeric all mean "unknown". Unknown refuses nothing: the save goes out and the
+ * server stays authoritative. Nothing here guesses a ceiling from a hostname,
+ * compression or a browser storage quota, and `document.upload.maxBytes` is a
+ * different promise about different bytes.
+ */
+
+import { hostMeta } from "./host-meta.js";
+
+// The limit the last discovery answer announced. Memoized beside `hostMeta`'s own
+// memoized promise, because a save reads it synchronously: the request a person feels
+// is the save, and holding it for a discovery round trip would make a first save wait
+// out a timeout on a host that has no `/_/meta` at all. Until an answer lands the
+// limit is unknown, which is the honest reading and refuses nothing.
+let limit = null;
+let measures = null;
+let asked = null;
+
+function advertised(meta) {
+  const value = meta?.document?.maxBytes;
+  return Number.isSafeInteger(value) && value > 0 ? value : null;
+}
+
+function adopt(meta) {
+  limit = advertised(meta);
+  measures = meta?.document?.maxBytesMeasures === 'file' ? 'file' : null;
+  return limit;
+}
+
+// A Document's live state rides in one <script merge="page"> tag that Hyperclay
+// stores apart from the file, and its limit (`maxBytesMeasures: 'file'`) is judged on
+// the body without that tag, the way the host's splitPage() cuts it: the whole line
+// when the tag stands alone on it, otherwise the tag itself. Where the host would not
+// split (no tag, two tags), the cut here can only make the count smaller, so the
+// host's own 413 stays the answer and nothing is refused that the host would store.
+const PAGE_TAG = /<script\b[^>]*\bmerge=(["'])page\1[^>]*>[\s\S]*?<\/script\s*>/i;
+
+export function storedFile(html, measure = measures) {
+  if (measure !== 'file' || typeof html !== 'string') return html;
+  const match = PAGE_TAG.exec(html);
+  if (!match) return html;
+  let start = match.index;
+  let end = start + match[0].length;
+  const from = html.lastIndexOf('\n', start - 1) + 1;
+  const newline = html.indexOf('\n', end);
+  const to = newline === -1 ? html.length : newline + 1;
+  if (!/\S/.test(html.slice(from, start)) && !/\S/.test(html.slice(end, to))) { start = from; end = to; }
+  return html.slice(0, start) + html.slice(end);
+}
+
+/**
+ * How big these exact bytes are, against a limit that may not be known.
+ *
+ * @param {string} html - the bytes a save would send
+ * @param {number} [maxBytes] - the host's advertised ceiling, if it advertised one
+ * @returns {{bytes: number, maxBytes: ?number, state: 'unknown'|'ok'|'near'|'over'}}
+ */
+export function saveSize(html, maxBytes) {
+  const bytes = new TextEncoder().encode(html).byteLength;
+  const known = Number.isSafeInteger(maxBytes) && maxBytes > 0;
+  return {
+    bytes, maxBytes: known ? maxBytes : null,
+    state: !known ? 'unknown' : bytes > maxBytes ? 'over' :
+      bytes >= Math.ceil(maxBytes * 0.8) ? 'near' : 'ok'
+  };
+}
+
+/**
+ * The limit the last discovery answer advertised, without asking the host.
+ *
+ * @returns {?number}
+ */
+export function knownSaveLimit() {
+  return limit;
+}
+
+/**
+ * Ask the host what it accepts, once per page.
+ *
+ * Joins the memoized discovery answer, so this never costs a second request. `fresh`
+ * asks again, for a caller that wants the ceiling as it stands now.
+ *
+ * @param {Object} [options]
+ * @param {boolean} [options.fresh]
+ * @returns {Promise<?number>} the advertised limit, or null when it announced none
+ */
+export function saveLimit({ fresh = false } = {}) {
+  if (fresh) {
+    asked = hostMeta({ fresh: true }).then(adopt);
+    return asked;
+  }
+  if (!asked) asked = hostMeta().then(adopt);
+  return asked;
+}
+
+/**
+ * `clay.save.limits`: the host's save ceiling, and whether it said one at all.
+ *
+ * @param {Object} [options]
+ * @param {boolean} [options.fresh]
+ * @returns {Promise<{maxBytes: ?number}>}
+ */
+export function saveLimits({ fresh = false } = {}) {
+  return saveLimit({ fresh }).then((maxBytes) => ({ maxBytes }));
+}
+
+/**
+ * `clay.save.inspect`: measure bytes that are not this page's document.
+ *
+ * No capture, no send, no baseline, no save claim, and nothing said to anybody about
+ * what this page currently holds: an import preview asks about candidate bytes.
+ *
+ * @param {string} html
+ * @returns {Promise<{bytes: number, maxBytes: ?number, state: string}>}
+ */
+export async function inspectSaveSize(html) {
+  const maxBytes = await saveLimit();
+  return saveSize(storedFile(html), maxBytes);
+}
+
+/**
+ * Say what the last real save attempt measured, on the document.
+ *
+ * @param {{bytes: number, maxBytes: ?number, state: string}} size
+ */
+export function announceSaveSize(size) {
+  const event = new CustomEvent('clay:save-size', { detail: size });
+  document.dispatchEvent(event);
+  // The notice is fetched only by a measurement near or over the ceiling, so most edit
+  // boots never download it; once loaded it listens for itself, and this replay of the
+  // event that fetched it only redraws in place.
+  if (size.state === 'near' || size.state === 'over') {
+    import('./save-size-notice.js').then((notice) => notice.start(event), () => {});
+  }
+}