@panphora/clayjs 1.13.1 → 1.14.0

package/src/core/save.js

@@ -13,7 +13,7 @@ import throttle from "../lib/throttle.js";
 import Mutation from "../lib/mutation.js";
 import { isDraftMode, isEditMode, isOwner } from "./is-edit-mode.js";
 import {
-  saveHtml,
+  saveCapturedHtml,
   getPageContents,
   replacePageWith as replacePageWithCore,
   addDocumentTransform,
@@ -27,6 +27,8 @@ 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 { registerStyleAdoption } from "../lib/style-adoption.js";
+import { styleComparisonStripper } from "./style-comparisons.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";
@@ -188,6 +190,8 @@ let unsavedChanges = false;
 // the split is observable there.
 let lastSavedContents = '';
 let lastSavedDirty = '';
+let baselineRevision = 0;
+const inFlightComparisons = new Set();
 // A save was requested while one was on the wire; run one more when it settles.
 let pendingSave = false;
 // An autosave arrived while one of our saves was on the wire. When that save lands
@@ -374,12 +378,11 @@ function skipped_(msg) {
  * where the write may or may not have landed, so it is not treated as success
  * either.
  */
-function applySaveResult(result, forComparison, forDirty, label, gateToken, forSave = null) {
+function applySaveResult(result, forComparison, forDirty, label, gateToken, forSave = null, captureId = null) {
   if (result.ok) {
     // Both baselines advance from the SAME pre-request capture, never from the
     // live DOM, so an edit made while the request was on the wire stays unsaved.
-    lastSavedContents = forComparison;
-    lastSavedDirty = forDirty;
+    setLastSavedBaselines(forComparison, forDirty);
     lastSavedBytes = forSave;
     unsavedChanges = false;
     // Generation-checked: clears the scoped-sync dirty gate only if nothing
@@ -397,9 +400,23 @@ function applySaveResult(result, forComparison, forDirty, label, gateToken, forS
       changedBy: result.changedBy ?? null,
       afterTimeout: result.afterTimeout === true,
       etag: result.conflictEtag ?? null,
+      code: result.code ?? null,
+      reason: result.reason ?? null,
+      retryAfter: result.retryAfter ?? null,
+      captureId,
     });
   } else if (result.msgType !== 'skipped') {
-    const extra = { status: result.status ?? null, hadTimeout: result.hadTimeout === true };
+    const extra = {
+      status: result.status ?? null,
+      hadTimeout: result.hadTimeout === true,
+      // The host's typed refusal, so a listener can react to the specific code
+      // rather than reading the message. `retryAfter` is only set where the host
+      // asked for a delay.
+      code: result.code ?? null,
+      reason: result.reason ?? null,
+      retryAfter: result.retryAfter ?? null,
+      captureId,
+    };
     if (!navigator.onLine) {
       setSaveState('offline', result.msg, '', extra);
     } else {
@@ -455,14 +472,14 @@ export function getLastSavedBytes() { return lastSavedBytes; }
 export function setLastSavedBaselines(forComparison, forDirty) {
   lastSavedContents = forComparison;
   lastSavedDirty = forDirty;
+  baselineRevision++;
 }
 
 // Kept for back-compat: a caller with one string means the page has no batching
 // region, or it does not know about the split. Setting both from it is the safe
 // reading, since the domains coincide exactly when there is no such region.
 export function setLastSavedContents(val) {
-  lastSavedContents = val;
-  lastSavedDirty = val;
+  setLastSavedBaselines(val, val);
 }
 
 /**
@@ -509,15 +526,15 @@ export function savePage(callback = () => {}) {
     // Single capture: clone once, get both versions
     // forSave strips non-persisted regions ([no-save]/[save-remove])
     // forComparison additionally strips every autosave-off region
-    let forSave, forComparison, forDirty;
+    let forSave, forComparison, forDirty, captureId;
     const gateToken = gateCaptureToken();
     try {
-      ({ forSave, forComparison, forDirty } = captureForSaveAndComparison());
+      ({ forSave, forComparison, forDirty, captureId } = captureForSaveAndComparison({ requestRefresh: true }));
     } catch (err) {
       console.error('savePage: captureForSaveAndComparison failed', err);
       clearExplicitSave();
-      setSaveState('error', err.message);
-      const result = { msg: err.message, msgType: 'error', code: null, etag: null };
+      setSaveState('error', err.message, '', { sent: false, code: err.code ?? null });
+      const result = { msg: err.message, msgType: 'error', code: err.code ?? null, etag: null };
       if (typeof callback === 'function') {
         callback(result);
       }
@@ -545,11 +562,14 @@ export function savePage(callback = () => {}) {
     // Start debounced 'saving' state (only shows if save takes >500ms)
     setSavingState();
 
-    // Use saveHtml directly with our pre-captured content (avoids double capture)
+    // Use the captured save path with our pre-captured content (avoids double capture)
+    const comparison = { forComparison, forDirty };
+    inFlightComparisons.add(comparison);
     ownSaveOnWire = true;
-    saveHtml(forSave, (result) => {
+    saveCapturedHtml(forSave, captureId, (result) => {
       ownSaveOnWire = false;
-      applySaveResult(result, forComparison, forDirty, 'updated after save', gateToken, forSave);
+      inFlightComparisons.delete(comparison);
+      applySaveResult(result, comparison.forComparison, comparison.forDirty, 'updated after save', gateToken, forSave, captureId);
       if (typeof callback === 'function') {
         callback(result);
       }
@@ -587,14 +607,14 @@ export function savePageForce(callback = () => {}) {
       setOfflineStateQuiet();
     }
 
-    let forSave, forComparison, forDirty;
+    let forSave, forComparison, forDirty, captureId;
     const gateToken = gateCaptureToken();
     try {
-      ({ forSave, forComparison, forDirty } = captureForSaveAndComparison());
+      ({ forSave, forComparison, forDirty, captureId } = captureForSaveAndComparison({ requestRefresh: true }));
     } catch (err) {
       console.error('savePageForce: captureForSaveAndComparison failed', err);
-      setSaveState('error', err.message);
-      const result = { msg: err.message, msgType: 'error', code: null, etag: null };
+      setSaveState('error', err.message, '', { sent: false, code: err.code ?? null });
+      const result = { msg: err.message, msgType: 'error', code: err.code ?? null, etag: null };
       if (typeof callback === 'function') {
         callback(result);
       }
@@ -603,10 +623,13 @@ export function savePageForce(callback = () => {}) {
 
     setSavingState();
 
+    const comparison = { forComparison, forDirty };
+    inFlightComparisons.add(comparison);
     ownSaveOnWire = true;
-    saveHtml(forSave, (result) => {
+    saveCapturedHtml(forSave, captureId, (result) => {
       ownSaveOnWire = false;
-      applySaveResult(result, forComparison, forDirty, 'updated after force save', gateToken, forSave);
+      inFlightComparisons.delete(comparison);
+      applySaveResult(result, comparison.forComparison, comparison.forDirty, 'updated after force save', gateToken, forSave, captureId);
       if (typeof callback === 'function') {
         callback(result);
       }
@@ -774,6 +797,17 @@ let baselineActive = true;
 let baselineSettledAt = false;
 export function baselineSettled() { return baselineSettledAt; }
 
+registerStyleAdoption(identity => {
+  const strip = styleComparisonStripper(identity);
+  lastSavedContents = strip(lastSavedContents);
+  lastSavedDirty = strip(lastSavedDirty);
+  baselineContents = strip(baselineContents);
+  for (const comparison of inFlightComparisons) {
+    comparison.forComparison = strip(comparison.forComparison);
+    comparison.forDirty = strip(comparison.forDirty);
+  }
+});
+
 // ============================================
 // BASELINE CAPTURE (Settled Signal)
 // ============================================
@@ -787,7 +821,7 @@ export function baselineSettled() { return baselineSettledAt; }
 // WHY IMMEDIATE + CONDITIONAL UPDATE:
 // We set baseline immediately as a safety net. If the user edits or saves
 // before settle completes, we don't overwrite their work. The settled snapshot
-// only replaces baseline if nothing changed (lastSavedContents === immediateContents).
+// only replaces baseline if no user input or baseline installation intervened.
 
 const SETTLE_MS = 500;        // Wait for no mutations for this long
 const MAX_SETTLE_MS = 3000;   // Max time to wait before forcing capture
@@ -803,8 +837,8 @@ function initBaselineCapture() {
   // This ensures saves during settle window work correctly
   // Store stripped version so comparisons are direct (no parsing needed)
   const { forComparison: immediateContents, forDirty: immediateDirty } = captureForComparisonAndDirty();
-  lastSavedContents = immediateContents;
-  lastSavedDirty = immediateDirty;
+  setLastSavedBaselines(immediateContents, immediateDirty);
+  const immediateRevision = baselineRevision;
   baselineContents = immediateContents;
   logBaseline('immediate capture', `${immediateContents.length} chars`);
 
@@ -829,18 +863,14 @@ function initBaselineCapture() {
     if (unsubscribeMutation) unsubscribeMutation();
     userEditEvents.forEach(evt => document.removeEventListener(evt, markUserEdited, true));
 
-    // Only update if no user edits AND no saves occurred during settle.
-    // BOTH baselines have to be untouched, not just the autosave one: a save
-    // whose only change was inside a batching region advances lastSavedDirty
-    // while leaving lastSavedContents byte-identical to the immediate capture.
-    // Checking one would let a second, unsent edit in that region be captured
-    // here as though it had been saved.
-    if (!userEdited && lastSavedContents === immediateContents && lastSavedDirty === immediateDirty) {
+    // Adoption only removes owned styles from comparison state. It does not
+    // advance this revision. A save or sync installation does, even when its
+    // comparison bytes match, so settle cannot absorb a later unsent edit.
+    if (!userEdited && baselineRevision === immediateRevision) {
       // Store stripped version so comparisons are direct (no parsing needed)
       const gateToken = gateCaptureToken();
       const { forComparison: contents, forDirty: contentsDirty } = captureForComparisonAndDirty();
-      lastSavedContents = contents;
-      lastSavedDirty = contentsDirty;
+      setLastSavedBaselines(contents, contentsDirty);
       baselineContents = contents;
       // Boot churn (modules rewriting attributes at DOM-ready) counted toward
       // the scoped-sync gate; the settled baseline is the proof it wasn't edits.

package/src/core/snapshot.js

@@ -58,6 +58,17 @@ const snapshotProvenance = new WeakMap();
 // second renderer would be two answers to "what bytes does this save send".
 let saveRenderer = null;
 
+// The capture identity for save captures. A refused save that may retry reads it
+// before sending and again before each retry: a capture newer than the one those
+// bytes describe means the attempt is already superseded and must not be re-sent.
+// It is an opaque local count, monotone per loaded module, and never goes on the
+// wire; it is what binds one capture to the exact requests that carried its body.
+let captureCounter = 0;
+
+export function currentCaptureId() {
+  return captureCounter;
+}
+
 export function originalSnapshotNode(cloneNode) {
   return snapshotProvenance.get(cloneNode) || null;
 }
@@ -224,7 +235,7 @@ function clonePreventingOnclone(node, deep = true) {
   finally { window.__preventOnclone = prev; }
 }
 
-export function captureSnapshot({ flushUndo = true, authored = true } = {}) {
+export function captureSnapshot({ flushUndo = true, authored = true, forSave = false, requestRefresh = false } = {}) {
   // Force-close any pending undo idle batch BEFORE cloning the DOM, so the
   // snapshot reflects a clean undo boundary. Without this, a save that fires
   // mid-typing would leave the idle batch open across the save boundary, and
@@ -245,7 +256,7 @@ export function captureSnapshot({ flushUndo = true, authored = true } = {}) {
 
   for (const hook of snapshotHooks) {
     stripSnapshotRegions(clone);
-    hook(clone, { original: originalSnapshotNode });
+    hook(clone, { original: originalSnapshotNode, forSave, requestRefresh });
   }
 
   // Put back any URL clay rewrote at runtime (cache-bust, refetch-on-save) so
@@ -327,6 +338,19 @@ export function captureSaveClone({ flushUndo = true, authored = true } = {}) {
   return prepareCloneForSave(captureSnapshot({ flushUndo, authored }), { authored });
 }
 
+// Attributes that render exactly like their absence. A scroll lock or a browser
+// extension that resets an inline style leaves `style=""` behind, and the dirty
+// check must not read that as an edit the person would lose on close.
+const EMPTY_INERT_ATTRS = ['style', 'class'];
+
+function serializeForCompare(clone) {
+  for (const name of EMPTY_INERT_ATTRS) {
+    if (clone.getAttribute(name) === '') clone.removeAttribute(name);
+    for (const el of clone.querySelectorAll(`[${name}=""]`)) el.removeAttribute(name);
+  }
+  return "<!DOCTYPE html>" + clone.outerHTML;
+}
+
 /**
  * Capture snapshot prepared for dirty/change comparison.
  *
@@ -355,7 +379,7 @@ export function captureForComparison({ flushUndo = true } = {}) {
 
   stripSnapshotRegions(clone);
 
-  return "<!DOCTYPE html>" + clone.outerHTML;
+  return serializeForCompare(clone);
 }
 
 /**
@@ -388,7 +412,7 @@ export function captureForDirtyCheck({ flushUndo = true } = {}) {
 
   stripSnapshotRegions(clone);
 
-  return "<!DOCTYPE html>" + clone.outerHTML;
+  return serializeForCompare(clone);
 }
 
 /**
@@ -419,7 +443,7 @@ export function captureForComparisonAndDirty({ flushUndo = true } = {}) {
     hook(clone);
   }
   stripSnapshotRegions(clone);
-  const forComparison = "<!DOCTYPE html>" + clone.outerHTML;
+  const forComparison = serializeForCompare(clone);
 
   let forDirty = forComparison;
   if (dirtyClone) {
@@ -431,7 +455,7 @@ export function captureForComparisonAndDirty({ flushUndo = true } = {}) {
       hook(dirtyClone);
     }
     stripSnapshotRegions(dirtyClone);
-    forDirty = "<!DOCTYPE html>" + dirtyClone.outerHTML;
+    forDirty = serializeForCompare(dirtyClone);
   }
 
   return { forComparison, forDirty };
@@ -445,10 +469,12 @@ export function captureForComparisonAndDirty({ flushUndo = true } = {}) {
  *
  * @param {Object} options
  * @param {boolean} options.emitForSync - Whether to emit snapshot-ready event (default: true)
- * @returns {{ forSave: string, forComparison: string, forDirty: string }}
+ * @returns {{ forSave: string, forComparison: string, forDirty: string, captureId: number }}
  */
-export function captureForSaveAndComparison({ emitForSync = true, flushUndo = true } = {}) {
-  const clone = captureSnapshot({ flushUndo });
+export function captureForSaveAndComparison({ emitForSync = true, flushUndo = true, requestRefresh = false } = {}) {
+  if (!Number.isSafeInteger(captureCounter + 1)) throw new Error('Save capture identity exhausted');
+  const captureId = ++captureCounter;
+  const clone = captureSnapshot({ flushUndo, forSave: emitForSync, requestRefresh });
 
   // Emit for live-sync before any stripping.
   //
@@ -459,7 +485,7 @@ export function captureForSaveAndComparison({ emitForSync = true, flushUndo = tr
   // and a baseline the dirty check cannot reproduce warns on close forever.
   if (emitForSync) {
     document.dispatchEvent(new CustomEvent('clay:snapshot-ready', {
-      detail: { documentElement: clone, forSave: true }
+      detail: { documentElement: clone, forSave: true, captureId }
     }));
   }
 
@@ -499,7 +525,7 @@ export function captureForSaveAndComparison({ emitForSync = true, flushUndo = tr
     hook(compareClone);
   }
   stripSnapshotRegions(compareClone);
-  const forComparison = "<!DOCTYPE html>" + compareClone.outerHTML;
+  const forComparison = serializeForCompare(compareClone);
 
   // Dirty clone: same shape as the compare clone, one selector weaker.
   let forDirty = forComparison;
@@ -512,10 +538,10 @@ export function captureForSaveAndComparison({ emitForSync = true, flushUndo = tr
       hook(dirtyClone);
     }
     stripSnapshotRegions(dirtyClone);
-    forDirty = "<!DOCTYPE html>" + dirtyClone.outerHTML;
+    forDirty = serializeForCompare(dirtyClone);
   }
 
-  return { forSave, forComparison, forDirty };
+  return { forSave, forComparison, forDirty, captureId };
 }
 
 /**

package/src/core/style-comparisons.js

@@ -0,0 +1,37 @@
+import { parse } from '../vendor/parse5.vendor.js';
+import { getStyleBaseUrl } from '../dom/insert-style-tag.js';
+
+export function styleComparisonStripper(identity) {
+  const cache = new Map();
+  return (html) => {
+    if (!html || !html.includes(identity.name !== undefined ? '<style' : '<link')) return html;
+    if (cache.has(html)) return cache.get(html);
+    const spans = [];
+    const tree = parse(html, { sourceCodeLocationInfo: true, scriptingEnabled: true });
+    const visit = (node) => {
+      const attrs = new Map((node.attrs || []).map(({ name, value }) => [name, value]));
+      const owned = identity.name !== undefined
+        ? node.tagName === 'style' && (attrs.get('data-name') === identity.name ||
+          (identity.legacyId !== undefined && attrs.get('id') === identity.legacyId && !attrs.has('data-name')))
+        : node.tagName === 'link' && attrs.get('rel')?.toLowerCase() === 'stylesheet' &&
+          getStyleBaseUrl(attrs.get('href') ?? null) === identity.href;
+      const loc = node.sourceCodeLocation;
+      if (owned && loc?.startTag) {
+        spans.push([loc.startTag.startOffset, loc.endTag?.endOffset ?? loc.endOffset]);
+      } else {
+        for (const child of node.childNodes || []) visit(child);
+      }
+    };
+    visit(tree);
+    spans.sort((a, b) => a[0] - b[0]);
+    let result = '';
+    let offset = 0;
+    for (const [from, to] of spans) {
+      result += html.slice(offset, from);
+      offset = to;
+    }
+    result += html.slice(offset);
+    cache.set(html, result);
+    return result;
+  };
+}

package/src/dom/insert-style-tag.js

@@ -1,3 +1,12 @@
+export function getStyleBaseUrl(url) {
+  try {
+    const parsed = new URL(url, window.location.href);
+    return parsed.origin + parsed.pathname;
+  } catch {
+    return url;
+  }
+}
+
 /**
  * Insert styles into the document (inline CSS or external stylesheet).
  *
@@ -62,24 +71,14 @@ function insertStyles(nameOrHref, cssOrCallback, callback) {
   const href = nameOrHref;
   const cb = typeof cssOrCallback === 'function' ? cssOrCallback : undefined;
 
-  // Helper to get base URL without query params (for comparison)
-  const getBaseUrl = (url) => {
-    try {
-      const parsed = new URL(url, window.location.href);
-      return parsed.origin + parsed.pathname;
-    } catch {
-      return url;
-    }
-  };
-
   // Normalize href to full URL path (without query params) for comparison
-  const normalizedHref = getBaseUrl(href);
+  const normalizedHref = getStyleBaseUrl(href);
 
   // Find all links with matching normalized path (ignoring query params like ?v=)
   const existingLinks = [...document.querySelectorAll('link[rel="stylesheet"]')]
     .filter(el => {
       try {
-        return getBaseUrl(el.getAttribute('href')) === normalizedHref;
+        return getStyleBaseUrl(el.getAttribute('href')) === normalizedHref;
       } catch {
         return false;
       }

package/src/lib/effect.js

@@ -0,0 +1,130 @@
+// clay.effect(fn): run fn soon and again after anything that can change what it
+// reads. Local edits arrive through the mutation hub; a live-sync merge runs with
+// the hub paused, so clay:sync-applied covers it; undo and redo write through the
+// hub as well, and their events are a backstop. fn runs with the hub paused, so
+// its own writes (derived counts, totals) never re-trigger it, never start an
+// autosave and never enter undo history. The first run is on a microtask too:
+// pausing the hub mid-way through an undo.commit would split the command. fn must
+// be synchronous: writes after an await land outside the pause and would loop.
+//
+// In edit mode each effect warns once about the misuses it can see: a write to
+// saved, dirty-tracked content (saved with the file, but never marks it unsaved),
+// an effect created inside an effect, undo.commit inside an effect (checked by the
+// undo plugin through effect.running), and an effect that keeps re-running.
+import { isTabLocalAttr } from "./root-attrs.js";
+
+const LOOP_RUNS = 50;
+const LOOP_WINDOW_MS = 1000;
+const NO_SNAPSHOT = '[clay~="no-snapshot"], [no-snapshot], [snapshot-remove]';
+
+let running = 0;
+
+const describe = (node) => {
+  const el = node.nodeType === 1 ? node : node.parentElement;
+  if (!el) return "a detached node";
+  let s = el.localName;
+  if (el.id) s += "#" + el.id;
+  else if (el.classList.length) s += "." + [...el.classList].slice(0, 2).join(".");
+  return "<" + s + ">";
+};
+
+function savedWrite(records) {
+  const policy = window.clay?.region?.resolveRegionPolicy;
+  if (!policy) return null;
+  const tracked = (el) => !!el && !el.closest(NO_SNAPSHOT) && policy(el).dirtyTracked;
+  for (const r of records) {
+    if (r.type === "attributes" && isTabLocalAttr(r.attributeName, r.target)) continue;
+    const el = r.target.nodeType === 1 ? r.target : r.target.parentElement;
+    if (!tracked(el)) continue;
+    // A child added or removed counts only when it is saved itself: chrome
+    // inserted into a saved parent (clay="editor-ui") is stripped on save.
+    if (r.type === "childList" && ![...r.addedNodes, ...r.removedNodes].some((n) => n.nodeType !== 1 || tracked(n))) continue;
+    return r.target;
+  }
+  return null;
+}
+
+export function effect(fn) {
+  const clay = window.clay;
+  const Mutation = clay.Mutation;
+  const warned = new Set();
+  const warn = (key, message) => {
+    if (warned.has(key)) return;
+    warned.add(key);
+    console.warn("clay.effect: " + message);
+  };
+  let queued = false;
+  let stopped = false;
+  let windowStart = 0;
+  let runs = 0;
+
+  if (running && clay.isEditMode) {
+    console.warn("clay.effect: an effect was created inside another effect, so a new one starts on every run. Create effects once, in clay.start.");
+  }
+
+  const watchLoop = () => {
+    const now = Date.now();
+    if (now - windowStart > LOOP_WINDOW_MS) { windowStart = now; runs = 0; }
+    if (++runs > LOOP_RUNS) {
+      warn("loop", `this effect ran more than ${LOOP_RUNS} times in a second. Something keeps changing the document, often a timer or async callback the effect started.`);
+    }
+  };
+
+  const run = () => {
+    queued = false;
+    if (stopped) return;
+    let observer = null;
+    Mutation.pause();
+    running++;
+    try {
+      if (clay.isEditMode === true) {
+        watchLoop();
+        if (!warned.has("saved")) {
+          observer = new MutationObserver(() => {});
+          observer.observe(document.documentElement, { subtree: true, childList: true, attributes: true, characterData: true });
+        }
+      }
+      const result = fn();
+      if (result && typeof result.then === "function") {
+        stop();
+        console.error("clay.effect: fn returned a promise. It must be synchronous, so this effect was stopped.");
+      }
+    } catch (err) {
+      console.error("clay.effect:", err);
+    } finally {
+      running--;
+      Mutation.resume();
+      const records = observer ? observer.takeRecords() : [];
+      observer?.disconnect();
+      if (records.length) {
+        const target = savedWrite(records);
+        if (target) {
+          warn("saved", `this effect changed ${describe(target)}, which is saved with the file. Effect writes never mark the page unsaved, so a merge can leave it dirty with no save scheduled. Draw derived values inside clay="no-dirty" or clay="editor-ui".`);
+        }
+      }
+    }
+  };
+  const schedule = () => {
+    if (queued || stopped) return;
+    queued = true;
+    queueMicrotask(run);
+  };
+
+  const offMutation = Mutation.onAnyChange({ debounce: 0, require: "observed" }, schedule);
+  document.addEventListener("clay:sync-applied", schedule);
+  clay.undo?.on?.("undo", schedule);
+  clay.undo?.on?.("redo", schedule);
+
+  const stop = () => {
+    stopped = true;
+    offMutation();
+    document.removeEventListener("clay:sync-applied", schedule);
+    clay.undo?.off?.("undo", schedule);
+    clay.undo?.off?.("redo", schedule);
+  };
+
+  schedule();
+  return stop;
+}
+
+Object.defineProperty(effect, "running", { get: () => running > 0 });

package/src/lib/style-adoption.js

@@ -0,0 +1,9 @@
+let adopter = () => {};
+
+export function registerStyleAdoption(fn) {
+  adopter = fn;
+}
+
+export function adoptStyleComparisons(identity) {
+  adopter(identity);
+}

package/src/lib/style.js

@@ -0,0 +1,44 @@
+import { insertStyles, getStyleBaseUrl } from "../dom/insert-style-tag.js";
+import Mutation from "./mutation.js";
+import { adoptStyleComparisons } from "./style-adoption.js";
+
+// A style a script owns. The tag saves with the page, so the next load paints
+// styled before any script runs. Each call writes the current CSS into the saved
+// tag in place (or points the saved <link> at the current href), so a page saved
+// by an older script picks up newer styles. The tag is no-dirty: an update is
+// carried by the next real save and never counts as an edit, starts an autosave
+// or raises the close warning.
+const markNoDirty = (el) => {
+  const tokens = (el.getAttribute("clay") ?? "").split(/\s+/).filter(Boolean);
+  if (!tokens.includes("no-dirty")) el.setAttribute("clay", [...tokens, "no-dirty"].join(" "));
+};
+
+export function style(nameOrHref, css) {
+  return writeStyle(nameOrHref, css);
+}
+
+export function styleWithLegacyId(name, css, legacyId) {
+  return writeStyle(name, css, legacyId);
+}
+
+function writeStyle(nameOrHref, css, legacyId) {
+  const inline = typeof css === "string";
+  const identity = inline ? { name: nameOrHref, legacyId } : { href: getStyleBaseUrl(nameOrHref) };
+  const legacy = legacyId === undefined ? [] : document.querySelectorAll(`style[id="${legacyId}"]:not([data-name])`);
+  Mutation.pause();
+  try {
+    adoptStyleComparisons(identity);
+    for (const el of legacy) el.dataset.name = nameOrHref;
+    if (inline) {
+      const el = insertStyles(nameOrHref, css, markNoDirty);
+      if (legacyId !== undefined) el.id = legacyId;
+      return el;
+    }
+    return insertStyles(nameOrHref, (link) => {
+      markNoDirty(link);
+      if (link.getAttribute("href") !== nameOrHref) link.setAttribute("href", nameOrHref);
+    });
+  } finally {
+    Mutation.resume();
+  }
+}