@panphora/clayjs 1.7.0 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panphora/clayjs",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "type": "module",
   "description": "clayjs: malleable HTML files. Save lifecycle for self-saving HTML.",
   "license": "MIT-0",
@@ -66,6 +66,7 @@
   },
   "devDependencies": {
     "@esm-bundle/chai": "^4.3.4-fix.0",
+    "@panphora/bevel": "0.1.0",
     "@web/test-runner": "^0.20.2",
     "@web/test-runner-commands": "^0.9.0",
     "@web/test-runner-playwright": "^0.11.1",

package/src/core/etag.js

@@ -10,8 +10,9 @@
  *
  * Three things move the stamp, and nothing else does:
  *
- *   - discovery seeds it, because a freshly loaded page has never saved and so
- *     holds no stamp of its own,
+ *   - the response that delivered this page seeds it, when the host stamped that
+ *     response: the stamp names the bytes the navigation was built from, which is
+ *     the only evidence this tab has about the version it is looking at,
  *   - an accepted save replaces it with the one that response carried, and clears
  *     it when a response carries none: after our own write, any stamp still held
  *     here is known to describe bytes the host has stopped storing,
@@ -19,6 +20,23 @@
  *     carried, because the file changed under a tab that never saved. A frame
  *     with no stamp on it falls back to clearing and asking the host.
  *
+ * Discovery seeds it only for a page that arrived without a stamp of its own. That
+ * is not a detail: both hosts read the file AGAIN when they answer discovery, so
+ * their answer describes a later moment than the navigation. This tab may have been
+ * served A, the file may have become B, and discovery answers B — bytes this tab has
+ * never seen. Adopting that would claim the newer version while holding the older
+ * bytes, and this tab's next save would pass If-Match and overwrite the update it
+ * never received. It would also erase the only evidence that the update is missing.
+ * The exception is an explicit overwrite, `seedEtag({ fresh: true })`, which a person
+ * asks for by name; that may take whatever the host says now.
+ *
+ * `represented` rides beside the stamp and answers a different question: which
+ * version of the file is the DOM in front of the person? A save compares against
+ * `lastSeen`, but discovery moves that without this tab having received anything, so
+ * the two only agree when the last change came with content. Startup repair compares
+ * the file against `represented` to decide whether this page is still the page the
+ * navigation delivered.
+ *
  * A peer's SNAPSHOT does not move it. §10 relays never write to disk, so the
  * stamp is still true after one lands, and treating one as a disk change would
  * refetch discovery on every keystroke another editor makes.
@@ -30,8 +48,13 @@
 
 import { hostMeta } from "./host-meta.js";
 import { isEditMode } from "./is-edit-mode.js";
+import { servedDocumentEtag } from "./host-attrs.js";
 
-let lastSeen = null;
+// Both start at the version this response was built from, when the host said which one
+// that is, so a page whose file changes before its first discovery answer still knows
+// what its own DOM came from.
+let lastSeen = servedDocumentEtag;
+let represented = servedDocumentEtag;
 let conditional = false;
 // Bumped by every write. A discovery answer that resolves after a save has
 // already recorded a newer stamp must not overwrite it.
@@ -54,6 +77,25 @@ export function conditionalSaves() {
 export function recordEtag(value) {
   lastSeen = typeof value === "string" && value !== "" ? value : null;
   generation++;
+  // Whatever this value came from — a save response, a disk frame, a deliberate
+  // forget — it describes content this tab has taken, so it is also what the tab
+  // represents.
+  represented = lastSeen;
+}
+
+/** The version of the file this tab's content came from, or null. */
+export function representedEtag() {
+  return represented;
+}
+
+/**
+ * Drop the represented stamp without touching the save stamp.
+ *
+ * For content that arrived with no version on it: the DOM now holds bytes the host
+ * never named, so this tab can no longer say which version it is looking at.
+ */
+export function forgetRepresentedEtag() {
+  represented = null;
 }
 
 /** Forget the stamp: the next save goes out unconditional. */
@@ -89,6 +131,13 @@ export async function seedEtag({ fresh = false, clearIfMissing = fresh } = {}) {
 
   if (generation !== at) return lastSeen;
 
+  // A stamped navigation is provenance, and discovery is not evidence about it. This
+  // answer is about a later moment than the response that built this page, so it may
+  // neither advance nor clear the stamp while this tab still represents what it was
+  // served. Only an explicit overwrite — fresh AND clearing allowed — moves it, and
+  // that is also the only case where an empty answer is taken as the truth.
+  if (servedDocumentEtag && !(fresh && clearIfMissing)) return lastSeen;
+
   const seed = meta.document?.etag;
   if (typeof seed === "string" && seed !== "") {
     lastSeen = seed;
@@ -120,6 +169,21 @@ export async function seedEtag({ fresh = false, clearIfMissing = fresh } = {}) {
 // A frame that live-sync HELD is deliberately not covered, because it never
 // dispatches this event. That tab has unsaved local edits and has not seen the
 // new disk bytes, which is precisely the case a 412 exists for.
+
+// The represented stamp goes first, and in both lanes. An unstamped disk apply leaves
+// this tab holding a DOM whose version nobody stated, so neither lane may keep claiming
+// the old one — a view-mode tab included, since that is the lane startup repair runs
+// in. A stamped frame needs nothing here: live-sync has already recorded it as part of
+// applying the content.
+document.addEventListener("clay:sync-applied", (event) => {
+  if (event.detail?.source !== "disk") return;
+  if (typeof event.detail.etag === "string" && event.detail.etag) return;
+  forgetRepresentedEtag();
+});
+
+// Edit mode goes further: the stamp it SAVES with has to move too, and the host is the
+// only source for the value, so it forgets the one it holds and asks again with the
+// overwrite flags. A view-mode tab never saves, so its save stamp can stay where it is.
 if (isEditMode) {
   document.addEventListener("clay:sync-applied", (event) => {
     if (event.detail?.source !== "disk") return;

package/src/core/host-attrs.js

@@ -9,6 +9,20 @@
 
 import { SAVE_TOKEN_ATTRS, LEGACY_SAVE_TOKEN_ATTRS } from "../lib/root-attrs.js";
 
+// The version of the bytes this response was built from, captured ONCE, here.
+//
+// §5's discovery answers about whatever is on disk when the ANSWER is built, which is
+// a later moment than the navigation that delivered this page: the file can change in
+// between, and its answer then names a revision this tab has never seen. The root
+// attribute is the only place that says which one this tab is actually looking at, so
+// it is read at module evaluation and never again. A later re-read would pick up
+// whatever a morph or a stream restart left on the root, which is exactly the claim
+// this value exists to avoid.
+export const servedDocumentEtag =
+  typeof document === "undefined"
+    ? null
+    : document.documentElement.getAttribute("documentetag") || null;
+
 let warnedAboutLegacyToken = false;
 
 /**

package/src/core/save.js

@@ -26,7 +26,7 @@ import { seedEtag, lastSeenEtag } from "./etag.js";
 import { gateCaptureToken, gateClearIfUnchanged, pageMaybeDirty } from "../lib/dirty-gate.js";
 import { hasUnsavedState } from "../lib/unsaved-state.js";
 import { autosaveActive } from "../lib/autosave-state.js";
-import { ROOT_LIBRARY_ATTRS, SAVE_TOKEN_ATTRS, LEGACY_SAVE_TOKEN_ATTRS } from "../lib/root-attrs.js";
+import { ROOT_LIBRARY_ATTRS, SAVE_TOKEN_ATTRS, LEGACY_SAVE_TOKEN_ATTRS, HOST_RESPONSE_ATTRS } from "../lib/root-attrs.js";
 import { logSaveCheck, logBaseline } from "../lib/autosave-debug.js";
 import { initUserGesture, markExplicitSave, clearExplicitSave } from "../lib/user-gesture.js";
 // A deliberate import cycle: unsaved-warning reads this module's saved baseline, and
@@ -51,16 +51,24 @@ addDocumentTransform(clone => {
   for (const name of ROOT_LIBRARY_ATTRS) clone.removeAttribute(name);
 });
 
-// Keep the host's save token out of the saved bytes, both spellings.
+// Keep the host's save token out of the saved bytes, both spellings, and the response
+// metadata with it.
 //
-// It is a credential for this response, never file content: htmlclay strips it from
-// every save body on arrival, so it never reached disk anyway. Sending it made the
+// A save token is a credential for this response, never file content: htmlclay strips it
+// from every save body on arrival, so it never reached disk anyway. Sending it made the
 // source map, which models the bytes a save sent, describe a root tag one attribute
 // longer than the file, and every offset after it was off by that much. The save
 // itself is authorized by the URL, which reads the token from the live page. The
 // document id is NOT stripped: htmlclay keeps it on disk on purpose.
+//
+// `documentetag` is the same kind of thing for a different reason. It names the version
+// of the response this tab loaded, and it is replaced on every serve, so writing it to
+// disk would freeze one response's stamp into the file and give the next reader a
+// provenance claim about bytes nobody built a response from. Root only, like the rest of
+// this transform: the same name on a child is the author's, and stripping those would
+// delete page content.
 addDocumentTransform(clone => {
-  for (const name of [...SAVE_TOKEN_ATTRS, ...LEGACY_SAVE_TOKEN_ATTRS]) clone.removeAttribute(name);
+  for (const name of [...SAVE_TOKEN_ATTRS, ...LEGACY_SAVE_TOKEN_ATTRS, ...HOST_RESPONSE_ATTRS]) clone.removeAttribute(name);
 });
 
 // ============================================

package/src/lib/root-attrs.js

@@ -63,6 +63,19 @@ export const LEGACY_SAVE_TOKEN_ATTRS = ["htmlclaytoken"];
 // what fixed that, and the split holds whatever token spellings are read above.
 export const HOST_IDENTITY_ATTRS = ["documentid", "htmlclayid"];
 
+// Response metadata, and neither of the other two. `documentetag` names the version
+// of the bytes the host built THIS response from, which is the one thing neither the
+// token nor the identity can say: a token grants a capability and an identity names a
+// file, while the stamp names a revision. It rides on the response only, so an
+// incoming morph must never apply a peer's copy and an outgoing sync must never carry
+// this tab's. Read once, at module evaluation, by host-attrs.js — never re-read from
+// the live root, which a morph may since have rewritten.
+//
+// Kept out of SAVE_TOKEN_ATTRS on purpose: host-attrs.js returns the first name it
+// finds in that list straight into the save URL, and a version stamp is not a
+// credential.
+export const HOST_RESPONSE_ATTRS = ["documentetag"];
+
 // What a host may have injected, and therefore what has to be stripped before a save
 // and kept out of an incoming morph. Wider than what is READ, on purpose: the old token
 // spelling is still injected by every htmlclay, so it still has to be stripped, whether
@@ -87,6 +100,7 @@ export const ROOT_LIBRARY_ATTRS = ["savestatus", "editmode", "pageowner"];
 // can no longer save at all.
 export const TAB_LOCAL_ROOT_ATTRS = new Set([
   ...HOST_TOKEN_ATTRS,
+  ...HOST_RESPONSE_ATTRS,
   ...ROOT_LIBRARY_ATTRS,
 ]);