@panphora/clayjs 1.15.2 → 1.17.0

package/src/plugins/visitor-drafts.js

@@ -5,15 +5,35 @@ import { createStore, safeStorage } from "./visitor-drafts/store.js";
 import { createUiMemory } from "./visitor-drafts/ui-memory.js";
 import { rememberSource, downloadUrl } from "./visitor-drafts/source.js";
 import { mountPrompt } from "./visitor-drafts/prompt.js";
-import { mountIntro } from "./visitor-drafts/intro.js";
-import { mountOwnerChip } from "./visitor-drafts/owner-chip.js";
-
-const DOWNLOAD_URL = "/_/download?as=htmlclay";
+import { DOWNLOAD_URL, backToDraft, editOriginal, inertVisitorDrafts } from "./visitor-drafts/inert.js";
 
 let store = null;
 let restoredDetail = null;
 let downloadLink = DOWNLOAD_URL;
 let source = null;
+let ready = Promise.resolve();
+
+// The chip is a convenience: a failed import leaves the draft working without it.
+function mountChip() {
+  return import("./visitor-drafts/owner-chip.js")
+    .then((m) => m.mountOwnerChip())
+    .catch((error) => {
+      console.warn("visitor-drafts: the owner chip did not load", error);
+      return null;
+    });
+}
+
+// Most visitors never see the intro (no template, a draft already kept, or dismissed),
+// so it is fetched only for a page that has one; a failed import costs only the intro.
+function mountIntroLate(options) {
+  if (!options.template) return Promise.resolve(null);
+  return import("./visitor-drafts/intro.js")
+    .then((m) => m.mountIntro(options))
+    .catch((error) => {
+      console.warn("visitor-drafts: the intro did not load", error);
+      return null;
+    });
+}
 
 const slot = draftSlot();
 const rulesTag = document.querySelector('script[data-rules-name~="api"]');
@@ -30,11 +50,11 @@ if (isDraftMode && slot && rulesTag) {
   const appName = document.querySelector('meta[name="application-name"]')?.content?.trim() || document.title.split(/:|\s\|\s/)[0].trim() || "This app";
   const template = document.querySelector("template[visitor-intro]");
   const start = () => {
-    const prompt = mountPrompt({ memory, appName, link: downloadLink });
-    mountIntro({ memory, template, appName, hadDraft: result.hadDraft });
-    if (isOwner) mountOwnerChip();
-    document.addEventListener("clay:drafts-store-failed", () => prompt.showError());
-    document.addEventListener("clay:drafts-saved", () => prompt.clearError());
+    ready = mountPrompt({ memory, appName, link: downloadLink }).then((prompt) => mountIntroLate({ memory, template, appName, hadDraft: result.hadDraft }).then(() => prompt)).then((prompt) => {
+      document.addEventListener("clay:drafts-store-failed", () => prompt.showError());
+      document.addEventListener("clay:drafts-saved", () => prompt.clearError());
+      return (isOwner ? mountChip() : Promise.resolve(null)).then(() => prompt);
+    });
   };
   document.readyState === "loading" ? document.addEventListener("DOMContentLoaded", start, { once: true }) : start();
   setDraftFlush(() => store.flush());
@@ -48,41 +68,10 @@ if (isDraftMode && slot && rulesTag) {
   if (!rulesTag) missing.push('a <script data-rules-name~="api"> rules tag');
   console.warn(`visitor-drafts: this page keeps no draft (missing ${missing.join(" and ")})`);
 } else if (isOwner && isEditMode && !hasSaveToken()) {
-  mountOwnerChip();
-}
-
-export const ready = Promise.resolve();
-
-function editOriginal() {
-  const url = new URL(window.location.href);
-  url.searchParams.set("editmode", "true");
-  window.location.href = url.toString();
-  return true;
-}
-
-function backToDraft() {
-  const url = new URL(window.location.href);
-  url.searchParams.delete("editmode");
-  window.location.href = url.toString();
-  return true;
+  ready = mountChip();
 }
 
-function inertVisitorDrafts() {
-  return {
-    active: false,
-    slot: null,
-    key: null,
-    hasDraft: () => false,
-    restored: () => null,
-    saveNow: () => false,
-    reset: () => false,
-    onRestore: () => false,
-    editOriginal,
-    backToDraft,
-    downloadUrl: () => DOWNLOAD_URL,
-    source: null,
-  };
-}
+export { ready };
 
 export const visitorDrafts = store ? {
   active: true,

package/src/plugins/wire.js

@@ -1,4 +1,4 @@
-import { isEditMode } from "../core/is-edit-mode.js";
+import { isEditMode, modeState } from "../core/is-edit-mode.js";
 import { saveToken } from "../core/host-attrs.js";
 import { hostMeta, hostSupports } from "../core/host-meta.js";
 
@@ -475,6 +475,80 @@ function releaseSaving(rec) {
   saveLane?.resumeAutosave();
 }
 
+// --- write admission -------------------------------------------------------
+
+// A request that asks for the page's own bytes is an edit-session operation: it flushes
+// the page and holds the save lane around the POST, so it may only start while the
+// session it was sent in still admits writes. The lease below closes that admission
+// while an exit drains and leaves an active save hold — this request's own operation —
+// pending until it settles, so an exit cannot report a clean view over an agent that is
+// still writing the file. A read-only request (`document: "none"`, which is every
+// helper and message workflow) is not gated: it writes nothing here.
+let session = null;
+
+const admits = () => !session || session.admitted;
+
+const fault = (message, code, pending) => Object.assign(new Error(`clay.wire: ${message}`), { code, pending });
+
+// The generation is what makes an await safe to come back from. A helper's identity
+// round trip, the save lane's import and the flush all outlive a switch that started
+// while they were in flight; the record is sent for the session it began in, and a
+// stale one ends as an error rather than handing an agent bytes from a session that
+// has gone.
+function admitsRecord(rec) {
+  if (rec.document !== "edit") return true;
+  if (rec.generation === modeState().generation && admits()) return true;
+  finish(rec, "error", "the page changed mode before this request went out", {
+    errorCode: "stale-document",
+    errorSource: "client",
+  });
+  return false;
+}
+
+/**
+ * The wire as a mode lease.
+ *
+ * Nothing to construct: the channel is lazy and belongs to the page. `quiesce` closes
+ * admission for edit requests and refuses the exit while one is still open, because
+ * that request's save hold is work the barrier cannot flush around — the hold stands
+ * until the request itself settles (a terminal frame, a cancel, or its deadline).
+ * `resume` reopens admission over the same records. `dispose` (after the barrier) only
+ * forgets the session: with none open the page is back to its unnegotiated rule.
+ *
+ * `initial: true` adopts the boot's rule instead of starting one: an explicit edit boot
+ * negotiated no session, so the adopted lease is admitted from the start and enable has
+ * nothing left to open.
+ */
+export function wireParticipant() {
+  return {
+    id: "clay:wire",
+    order: 900,
+    prepare(context = {}) {
+      const lease = { admitted: context.initial === true };
+      session = lease;
+      return {
+        enable() {
+          if (session === lease) lease.admitted = true;
+        },
+        quiesce() {
+          if (session !== lease) return;
+          lease.admitted = false;
+          const pending = [...records.values()]
+            .filter((rec) => rec.document === "edit" && (rec.holdsSave || OPEN_STATES.has(rec.state)))
+            .map((rec) => rec.id);
+          if (pending.length) throw fault("a request on this page has not settled", "pending-input", pending);
+        },
+        resume() {
+          if (session === lease) lease.admitted = true;
+        },
+        dispose() {
+          if (session === lease) session = null;
+        },
+      };
+    },
+  };
+}
+
 function once(eventName, timeout) {
   return new Promise((resolve) => {
     let done = false;
@@ -616,6 +690,7 @@ function send(payload, opts = {}) {
     landingTimer: null,
     abort: typeof AbortController === "function" ? new AbortController() : null,
     holdsSave: false,
+    generation: modeState().generation,
     settle: null,
     signal: opts.signal && typeof opts.signal.addEventListener === "function" ? opts.signal : null,
     signalHandler: null,
@@ -649,12 +724,16 @@ function send(payload, opts = {}) {
       }
     }
 
+    if (!admitsRecord(rec)) return;
+
     if (rec.document === "edit") {
       await holdSaving(rec);
       if (rec.state !== "sent") return;
+      if (!admitsRecord(rec)) return;
 
       await flushSave();
       if (rec.state !== "sent") return;
+      if (!admitsRecord(rec)) return;
     }
 
     // Subscribe before posting. A handler can acknowledge in single-digit
@@ -804,6 +883,8 @@ async function helpers() {
     .map(({ name, state }) => ({ name, state }));
 }
 
+export { wireParticipant as modeParticipant };
+
 export const wire = { send, cancel, get, list, isBusy, on, helpers };
 
 export default wire;

package/src/reader-core.js

@@ -0,0 +1,26 @@
+// The always-wave core as one module graph for the built release. The chunk build
+// makes this an entry and rewrites the loader's always-wave thunks to read the
+// namespace each path names here, so a page fetches one file instead of six while
+// the loader still activates the core before any plugin, in this order.
+//
+// The import list is CORE_WAVES.always (src/loader-logic.js), written out because
+// import statements cannot be computed. tests/unit/build/reader-core-order.test.js
+// runs the built graph and the source graph and compares their evaluation order, so
+// a module added to that wave without a line here fails a test instead of quietly
+// moving to the end. Source mode never imports this file.
+import * as mutation from "./lib/mutation.js";
+import * as preserveAuthored from "./core/preserve-authored.js";
+import * as editMode from "./core/edit-mode.js";
+import * as modeKey from "./core/mode-key.js";
+import * as staleHostNotice from "./core/stale-host-notice.js";
+import * as pageData from "./core/page-data.js";
+
+// Keyed by the logical path the loader and the manifest use.
+export const core = {
+  "lib/mutation.js": mutation,
+  "core/preserve-authored.js": preserveAuthored,
+  "core/edit-mode.js": editMode,
+  "core/mode-key.js": modeKey,
+  "core/stale-host-notice.js": staleHostNotice,
+  "core/page-data.js": pageData,
+};

package/src/recovery/conflicts.js

@@ -0,0 +1,287 @@
+/**
+ * conflicts.js — the durable half of the conflict ledger.
+ *
+ * The ledger (sync/conflicts.js) keeps what an incoming frame won over this tab's
+ * editing, and it keeps it in memory: the root the merge read as "mine", the nodes
+ * the report pointed at, the conflict records themselves. A reload takes every one
+ * of those away, and replaying the paths afterwards would point at a DOM that is
+ * not the one they were recorded against. So the ledger hands this module the
+ * material it cannot rebuild — the pre-apply root as bytes, and the conflicts as
+ * plain fields — and this module stores them in the shared recovery store.
+ *
+ * One record per apply: the root is stored once, and the conflicts reference it.
+ * The word "durable" means one completed IndexedDB transaction, and nothing more:
+ * a stored record is not a save, and the page never renders from it.
+ *
+ * What reaches IndexedDB is strings, numbers and booleans. A DOM node, a function,
+ * a Map or anything else the structured clone algorithm would refuse is dropped
+ * from the record and named in `dropped`, because one uncloneable field must not
+ * cost somebody the whole copy. The store's own refusal (quota, unknown schema,
+ * an unreachable database) is reported as a code and never removes the live
+ * conflict, which is still the person's copy in this tab.
+ */
+
+import { storage } from "../lib/doc-storage.js";
+
+export const CONFLICTS_CHANNEL = "clay.conflicts";
+export const CONFLICTS_VERSION = 1;
+export const CONFLICTS_KIND = "conflict";
+
+// A cheap read for the notice's shell, which must not open the database on every
+// edit boot. It says only that this document has stored conflicts to review.
+const HINT_KEY = "conflicts";
+
+const CONTEXT_FIELDS = ["kind", "id", "label", "field"];
+
+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: CONFLICTS_CHANNEL, version: CONFLICTS_VERSION }),
+    };
+  } catch (_) {
+    return null;
+  }
+  return registered.channel;
+}
+
+/**
+ * How many conflicts this document's store is holding for review, without opening
+ * the database. Zero means the notice's shell stays asleep.
+ *
+ * @returns {number}
+ */
+export function pendingConflicts() {
+  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);
+}
+
+const DROPPED = Symbol("dropped");
+
+function isPlainObject(value) {
+  if (!value || typeof value !== "object") return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+function copyField(value, dropped, field) {
+  const type = typeof value;
+  if (value === null || type === "string" || type === "number" || type === "boolean") return value;
+  if (type === "undefined") return DROPPED;
+  if (type !== "object") {
+    dropped.push(field);
+    return DROPPED;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item, at) => {
+      const kept = copyField(item, dropped, `${field}[${at}]`);
+      return kept === DROPPED ? null : kept;
+    });
+  }
+  if (!isPlainObject(value)) {
+    dropped.push(field);
+    return DROPPED;
+  }
+  const out = {};
+  for (const [key, item] of Object.entries(value)) {
+    const kept = copyField(item, dropped, field ? `${field}.${key}` : key);
+    if (kept !== DROPPED) out[key] = kept;
+  }
+  return out;
+}
+
+/**
+ * A copy that survives the trip into IndexedDB: plain objects, arrays, strings,
+ * numbers and booleans, with everything else dropped and named.
+ *
+ * @param {*} value
+ * @param {string[]} [dropped] - collects the fields that could not be stored
+ * @param {string} [field]
+ * @returns {*}
+ */
+export function plainCopy(value, dropped = [], field = "") {
+  const kept = copyField(value, dropped, field);
+  return kept === DROPPED ? null : kept;
+}
+
+/**
+ * The part of a conflict's context that can be stored: its identity, its label and
+ * its field. The resolver's `open` is a function bound to this page's tree, so it
+ * lives on the live record and never here.
+ *
+ * @param {*} context
+ * @returns {?Object}
+ */
+export function storedContext(context) {
+  if (!context || typeof context !== "object") return null;
+  const out = {};
+  for (const field of CONTEXT_FIELDS) {
+    const value = context[field];
+    if (typeof value === "string") {
+      if (value) out[field] = value;
+    } else if (typeof value === "number" && Number.isFinite(value)) {
+      out[field] = String(value);
+    }
+  }
+  return Object.keys(out).length ? out : null;
+}
+
+/**
+ * Copy one apply and its conflicts into the recovery store, before the ledger
+ * releases any of it.
+ *
+ * Returns synchronously with the staged ids: the copy is already in memory and the
+ * write is under way. It is a recovery copy, not a durable receipt.
+ *
+ * @param {Object} spec
+ * @param {Object} spec.apply - the ledger's apply, without its DOM roots
+ * @param {?string} spec.root - the pre-apply root as saved bytes
+ * @param {Object[]} spec.conflicts - plain conflict entries
+ * @returns {{id: *, revision: number}[]}
+ */
+export function recordConflicts({ apply = {}, root = null, conflicts = [] } = {}) {
+  const entries = [];
+  for (const conflict of conflicts) {
+    const dropped = [];
+    const entry = plainCopy(conflict, dropped, "");
+    if (!entry || typeof entry !== "object" || !entry.id) continue;
+    if (dropped.length) entry.dropped = dropped;
+    entries.push(entry);
+  }
+  if (!entries.length) return [];
+  const payload = {
+    apply: plainCopy(apply, [], "") ?? {},
+    root: typeof root === "string" ? root : null,
+    savedAt: Date.now(),
+    conflicts: entries,
+  };
+  try {
+    const ch = channel();
+    if (!ch) return [];
+    const staged = ch.stage({ key: String(apply.id ?? ""), kind: CONFLICTS_KIND, payload });
+    ch.flush().catch(() => {});
+    noteHint(pendingConflicts() + entries.length);
+    return [{ id: staged.id, revision: staged.revision }];
+  } catch (err) {
+    // The live conflict is the copy that matters right now: nothing is removed here.
+    console.error("clayjs: the conflict could not be stored for a later reload; it is still here", err);
+    return [];
+  }
+}
+
+const textOf = (value) => (typeof value === "string" ? value : value == null ? "" : String(value));
+
+function usableConflict(conflict) {
+  if (!conflict || typeof conflict !== "object") return null;
+  const id = textOf(conflict.id);
+  if (!id) return null;
+  const context = storedContext(conflict.context);
+  return {
+    id,
+    kind: textOf(conflict.kind),
+    key: textOf(conflict.key),
+    name: textOf(conflict.name),
+    sentence: textOf(conflict.sentence),
+    yours: textOf(conflict.yours),
+    now: textOf(conflict.now),
+    context,
+    dropped: Array.isArray(conflict.dropped) ? conflict.dropped.map(textOf) : [],
+  };
+}
+
+function usableRecord(record) {
+  const payload = record?.payload;
+  if (!payload || typeof payload !== "object") return null;
+  const conflicts = Array.isArray(payload.conflicts) ? payload.conflicts.map(usableConflict).filter(Boolean) : [];
+  if (!conflicts.length) return null;
+  const apply = payload.apply && typeof payload.apply === "object" ? payload.apply : {};
+  return {
+    id: record.id,
+    revision: record.revision,
+    supported: record.supported !== false,
+    savedAt: Number.isFinite(payload.savedAt) ? payload.savedAt : null,
+    apply,
+    root: typeof payload.root === "string" ? payload.root : null,
+    conflicts,
+  };
+}
+
+/**
+ * Every stored conflict for this document, from every writer: a record does not
+ * belong to the tab that made it, because the tab that made it may be gone.
+ *
+ * @returns {Promise<{ok: boolean, code?: string, records: Object[], status?: Object}>}
+ */
+export async function listConflicts() {
+  const ch = channel();
+  if (!ch) return { ok: true, records: [] };
+  let listed;
+  try {
+    listed = await ch.list();
+  } catch (_) {
+    return { ok: false, code: "error", records: [] };
+  }
+  if (!listed.ok) return { ok: false, code: listed.code, records: [] };
+  const records = listed.records.map(usableRecord).filter(Boolean);
+  noteHint(records.reduce((sum, record) => sum + record.conflicts.length, 0));
+  return { ok: true, records, status: listed.status };
+}
+
+/**
+ * Acknowledge conflicts, by the id the ledger gave them. This is the only way a
+ * stored conflict leaves: a person said so, or a live conflict was accepted,
+ * reverted or reconciled and its own record has already gone.
+ *
+ * Only the named conflicts go. A record that still holds another conflict keeps
+ * its root, so the surviving text is never lost because a neighbour was dismissed;
+ * the remainder is written under a new revision before the old one is deleted, so
+ * a failed write leaves the original exactly as it was.
+ *
+ * @param {string[]} ids
+ * @returns {Promise<{ok: boolean, code?: string, removed?: number}>}
+ */
+export async function dismissConflicts(ids) {
+  const wanted = new Set((Array.isArray(ids) ? ids : [ids]).filter((id) => id != null).map(String));
+  if (!wanted.size) return { ok: true, removed: 0 };
+  const ch = channel();
+  if (!ch) return { ok: true, removed: 0 };
+  const listed = await listConflicts();
+  if (!listed.ok) return { ok: false, code: listed.code };
+  let removed = 0;
+  for (const record of listed.records) {
+    const remaining = record.conflicts.filter((entry) => !wanted.has(entry.id));
+    if (remaining.length === record.conflicts.length) continue;
+    removed += record.conflicts.length - remaining.length;
+    if (!remaining.length) {
+      await ch.dismiss(record.id, { revision: record.revision });
+      continue;
+    }
+    ch.stage({
+      key: String(record.id),
+      kind: CONFLICTS_KIND,
+      payload: { apply: record.apply, root: record.root, savedAt: record.savedAt, conflicts: remaining },
+    });
+    const written = await ch.flush();
+    if (!written.ok) continue;
+    await ch.dismiss(record.id, { revision: record.revision });
+  }
+  await listConflicts();
+  // The notice may be holding a record this just changed.
+  globalThis.document?.dispatchEvent(new CustomEvent("clay:conflict-store-changed"));
+  return { ok: true, removed };
+}

package/src/recovery/identity.js

@@ -0,0 +1,154 @@
+/**
+ * identity.js — which recovery records belong to this document, and who is writing.
+ *
+ * Two tabs on one file must not overwrite each other's unsaved writing, and two
+ * documents on one origin (every file on a hyperclay.com subdomain) must not share
+ * a record at all. So a record is filed under a four-part scope plus a writer, and
+ * this module is the one place that decides both.
+ *
+ * The document half is the host's own file identity: `documentid`, or the pre-rename
+ * `htmlclayid` a document saved before that rename still carries on disk. It is read
+ * from HOST_IDENTITY_ATTRS, never from the save-token list, because a name in that
+ * list becomes a credential in the save URL. The root is read ONCE, here: a morph or
+ * a stream restart can rewrite the root afterwards, and a re-read would file this
+ * tab's writing under a document it is not looking at. `check()` reads the root
+ * again only to report that mismatch, and never to change the scope.
+ *
+ * Without a host identity the exact pathname is the identity: no query, no hash, and
+ * no decoding of distinct paths into one. A draft is always path-scoped, because a
+ * visitor's draft never reaches the host's file and this browser is the only place
+ * it lives. Nothing here makes a request; a draft must not ask the host anything.
+ */
+
+import { HOST_IDENTITY_ATTRS } from "../lib/root-attrs.js";
+
+export const PATH_KIND = "path";
+export const EDIT_MODE = "edit";
+export const DRAFT_MODE = "draft";
+
+/**
+ * A fresh writer id, once per page load.
+ *
+ * Never from sessionStorage: a duplicated tab inherits that storage, and two tabs
+ * holding one writer id would overwrite each other's recovery for the same key.
+ *
+ * @returns {string}
+ */
+export function newWriterId() {
+  const minted = globalThis.crypto?.randomUUID?.();
+  if (minted) return minted;
+  return `wr-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+
+/**
+ * The durable file identity this response carries, or null.
+ *
+ * Host-injected and stripped before saving, so it names a file and not a revision.
+ * A response carrying neither spelling is a downloaded copy, a local file, or a
+ * host that mints no identity, and all three fall back to the pathname.
+ *
+ * @param {?Element} [root] - the document's root element
+ * @returns {?{kind: string, identity: string}}
+ */
+export function hostIdentityOf(root = globalThis.document?.documentElement) {
+  if (!root || typeof root.getAttribute !== "function") return null;
+  for (const attr of HOST_IDENTITY_ATTRS) {
+    const value = root.getAttribute(attr);
+    if (value) return { kind: attr, identity: value };
+  }
+  return null;
+}
+
+/**
+ * The pathname as an identity: no query, no hash, nothing decoded.
+ *
+ * Two URLs that differ only in how they were opened are one document. A caller
+ * that hands over a whole URL string still gets the path, because filing one
+ * document's writing under two identities is how recovery goes missing.
+ *
+ * @param {string} pathname
+ * @returns {{kind: string, identity: string}}
+ */
+export function pathIdentityOf(pathname) {
+  const identity = String(pathname || "/").split(/[?#]/)[0];
+  return { kind: PATH_KIND, identity: identity || "/" };
+}
+
+/**
+ * This page's recovery identity: its scope, its writer, and a check on the root.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.mode] - "edit" or "draft"
+ * @param {?Element} [options.root]
+ * @param {?Location} [options.location]
+ * @param {string} [options.pathname]
+ * @param {string} [options.origin]
+ * @param {string} [options.writerId]
+ * @returns {Object}
+ */
+/**
+ * Whether two authorities are the same document, seen by the same account.
+ *
+ * `principalId` is the account, never a token, and a changed login is another principal:
+ * a journal is replayed into the authority and principal it was written under or not at
+ * all. A missing field is never equal to a missing field.
+ *
+ * @param {?Object} a
+ * @param {?Object} b
+ * @returns {boolean}
+ */
+export function sameAuthority(a, b) {
+  if (!a || !b) return false;
+  if (!a.host || !a.documentId || !a.principalId) return false;
+  return a.host === b.host && a.documentId === b.documentId && a.principalId === b.principalId;
+}
+
+export function createIdentity({
+  mode = EDIT_MODE,
+  root = globalThis.document?.documentElement,
+  location: where = globalThis.window?.location,
+  pathname,
+  origin,
+  writerId,
+} = {}) {
+  const scopeMode = mode === DRAFT_MODE ? DRAFT_MODE : EDIT_MODE;
+  const path = pathname ?? where?.pathname ?? "/";
+  const from = origin ?? where?.origin ?? "";
+  const pathIdentity = pathIdentityOf(path);
+  const hostIdentity = scopeMode === DRAFT_MODE ? null : hostIdentityOf(root);
+  const captured = hostIdentity ?? pathIdentity;
+  const scope = [from, captured.kind, captured.identity, scopeMode];
+
+  return {
+    origin: from,
+    pathname: path,
+    mode: scopeMode,
+    scope,
+    writerId: writerId || newWriterId(),
+    identityKind: captured.kind,
+    identity: captured.identity,
+
+    /**
+     * Is the root still naming the document this page filed its records under?
+     *
+     * A mismatch is reported, never applied: records written under one identity are
+     * not moved into another document's scope by a later root rewrite. A host
+     * identity that appears after this load is a later binding, and the records stay
+     * where they are until a confirmed move offers both scopes for review.
+     *
+     * @param {?Element} [next]
+     * @returns {{ok: boolean, code: ?string}}
+     */
+    check(next = globalThis.document?.documentElement) {
+      const found = hostIdentityOf(next);
+      if (!hostIdentity) {
+        return found ? { ok: true, code: null, bound: found, scope } : { ok: true, code: null };
+      }
+      if (!found) return { ok: false, code: "identity-missing", captured: hostIdentity, scope };
+      if (found.kind !== hostIdentity.kind || found.identity !== hostIdentity.identity) {
+        return { ok: false, code: "identity-mismatch", captured: hostIdentity, found, scope };
+      }
+      return { ok: true, code: null };
+    },
+  };
+}