@panphora/clayjs 1.17.0 → 1.18.0

package/src/core/source-map.js

@@ -21,6 +21,11 @@
  *   verify(out, today)    reparse and compare trees before anything is sent
  *   adopt(bytes)          re-model and re-pair against what the host accepted
  *
+ * EVERY EXPENSIVE WALK IS A GENERATOR. `modelSteps`, `pairCapturedSteps`, `vDiffSteps`,
+ * `vParseErrorsSteps` and the verifier built from them yield between whole units of work,
+ * and the synchronous functions are `drain` of those generators (`src/lib/slice.js`). One
+ * walk, so a sliced run and a one-shot run cannot disagree about what this module says.
+ *
  * THE FLOOR IS TODAY'S BEHAVIOUR. Anything that does not verify is sent as the full
  * serialization instead, and counted. A fetch that does not return this document, a
  * source whose shape outside <html> disagrees with the live document, a render that
@@ -37,13 +42,17 @@
  *   of this code wrote `by <a>Ana</a> <a>Bo</a>` back as `AnaBo` with a green check.
  */
 
-import { parse } from '../vendor/parse5.vendor.js';
+import { parseSteps } from '../source/parse-steps.js';
+import { drain } from '../lib/slice.js';
 
 const RAW_TEXT = new Set(['script', 'style', 'xmp', 'iframe', 'noembed', 'noframes', 'plaintext', 'noscript']);
 const RCDATA = new Set(['textarea', 'title']);
 const textContext = (tag) => (RAW_TEXT.has(tag) ? 'raw' : RCDATA.has(tag) ? 'rcdata' : 'normal');
 const VOID = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr']);
 const XHTML = 'http://www.w3.org/1999/xhtml';
+// Nodes one walk compares between two yields. It only decides where a sliced walk may
+// pause; the walk itself is the same walk at any value.
+const YIELD_EVERY = 1500;
 
 const escText = (s) => s.replace(/&/g, '&amp;').replace(/ /g, '&nbsp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 const escAttr = (s) => s.replace(/&/g, '&amp;').replace(/ /g, '&nbsp;').replace(/"/g, '&quot;');
@@ -53,16 +62,21 @@ const escAttr = (s) => s.replace(/&/g, '&amp;').replace(/ /g, '&nbsp;').replace
 // =============================================================================
 
 export function model(src) {
-  // The error counts come out of the SAME parse, so they cost nothing here. They are
-  // the only evidence of input a parser throws away, which a tree comparison cannot
-  // see by construction: a duplicate attribute is discarded during parsing, so a render
-  // that wrote one twice reparsed to exactly the right tree. That is how the same
-  // `xmlns:xlink` was added to a file on every save with the verifier green each time.
-  const parseErrors = new Map();
-  const doc = parse(src, {
-    sourceCodeLocationInfo: true,
-    onParseError: (e) => parseErrors.set(e.code, (parseErrors.get(e.code) || 0) + 1),
-  });
+  return drain(modelSteps(src));
+}
+
+/**
+ * The same model, parsed in slices so a large document does not hold the thread for the
+ * whole parse.
+ *
+ * The error counts come out of the SAME parse, so they cost nothing here. They are the
+ * only evidence of input a parser throws away, which a tree comparison cannot see by
+ * construction: a duplicate attribute is discarded during parsing, so a render that wrote
+ * one twice reparsed to exactly the right tree. That is how the same `xmlns:xlink` was
+ * added to a file on every save with the verifier green each time.
+ */
+export function* modelSteps(src) {
+  const { document: doc, errors: parseErrors } = yield* parseSteps(src, { sourceCodeLocationInfo: true });
   return modelFromParsed(src, doc, parseErrors);
 }
 
@@ -350,10 +364,26 @@ function keysOfLive(n, keyMap) {
   keyMap.set(n, k);
   return k;
 }
-function keysOfLoc(loc) {
+function* keysOfLiveSteps(n, keyMap, walked) {
+  if (++walked.n % YIELD_EVERY === 0) yield;
+  let k;
+  if (n.nodeType === 3) k = { tag: '#text', shallow: 't:' + n.data, content: 't:' + n.data, deep: 't:' + n.data };
+  else if (n.nodeType === 8) k = { tag: '#comment', shallow: 'c:' + n.data, content: 'c:' + n.data, deep: 'c:' + n.data };
+  else {
+    const kids = [];
+    for (const c of liveKids(n)) kids.push(yield* keysOfLiveSteps(c, keyMap, walked));
+    const shallow = 'e:' + n.localName + '|' + liveAttrsKey(n);
+    k = { tag: n.localName, shallow, content: 'e:' + n.localName + '|' + hashKey(kids.map((c) => c.content)), deep: shallow + '|' + hashKey(kids.map((c) => c.deep)) };
+  }
+  keyMap.set(n, k);
+  return k;
+}
+function* keysOfLocSteps(loc, walked) {
+  if (++walked.n % YIELD_EVERY === 0) yield;
   if (loc.kind === 'text') return (loc.keys = { tag: '#text', shallow: 't:' + loc.value, content: 't:' + loc.value, deep: 't:' + loc.value });
   if (loc.kind === 'comment') return (loc.keys = { tag: '#comment', shallow: 'c:' + loc.value, content: 'c:' + loc.value, deep: 'c:' + loc.value });
-  const kids = loc.children.map(keysOfLoc);
+  const kids = [];
+  for (const c of loc.children) kids.push(yield* keysOfLocSteps(c, walked));
   const shallow = 'e:' + loc.tag + '|' + srcAttrsKey(loc);
   return (loc.keys = { tag: loc.tag, shallow, content: 'e:' + loc.tag + '|' + hashKey(kids.map((c) => c.content)), deep: shallow + '|' + hashKey(kids.map((c) => c.deep)) });
 }
@@ -493,10 +523,16 @@ function describeLoc(l) {
  * @param {Function} [resolve] - node -> the identity to key the map by (default: itself)
  */
 export function pair(root, m, resolve = (n) => n) {
+  return drain(pairSteps(root, m, resolve));
+}
+
+/** The same pairing pass, `yield`ing every `YIELD_EVERY` nodes hashed or bound. */
+export function* pairSteps(root, m, resolve = (n) => n) {
   const map = new WeakMap();
   const keyMap = new Map();
-  keysOfLive(root, keyMap);
-  keysOfLoc(m.root);
+  const walked = { n: 0 };
+  yield* keysOfLiveSteps(root, keyMap, walked);
+  yield* keysOfLocSteps(m.root, walked);
   const stats = { paired: 0, unmatchedLive: [], unmatchedSource: [], attrDiffs: [], textDiffs: 0, unresolved: 0 };
   // A token identifying THIS pairing pass, stamped on the model and on every loc that
   // binds. render trusts a loc only when the two still agree, which rules out a loc
@@ -505,11 +541,12 @@ export function pair(root, m, resolve = (n) => n) {
   // model, so holding the node here would keep every node the page has since deleted.
   const gen = {};
   m.gen = gen;
-  bind(root, m.root, map, keyMap, stats, 'html', resolve, gen);
+  yield* bindSteps(root, m.root, map, keyMap, stats, 'html', resolve, gen, walked);
   return { map, stats };
 }
 
-function bind(node, loc, map, keyMap, stats, path, resolve, gen) {
+function* bindSteps(node, loc, map, keyMap, stats, path, resolve, gen, walked) {
+  if (++walked.n % YIELD_EVERY === 0) yield;
   const key = resolve(node);
   if (key) { map.set(key, loc); loc.gen = gen; stats.paired++; }
   else stats.unresolved++;
@@ -520,7 +557,7 @@ function bind(node, loc, map, keyMap, stats, path, resolve, gen) {
   const usedL = new Set(), usedS = new Set();
   for (const [i, j] of pairs) {
     usedL.add(i); usedS.add(j);
-    bind(L[i], S[j], map, keyMap, stats, path + '>' + (L[i].nodeType === 1 ? L[i].localName : '#') + '[' + i + ']', resolve, gen);
+    yield* bindSteps(L[i], S[j], map, keyMap, stats, path + '>' + (L[i].nodeType === 1 ? L[i].localName : '#') + '[' + i + ']', resolve, gen, walked);
   }
   for (let i = 0; i < L.length; i++) if (!usedL.has(i)) stats.unmatchedLive.push({ path, node: describe(L[i]) });
   for (let j = 0; j < S.length; j++) if (!usedS.has(j)) stats.unmatchedSource.push({ path, node: describeLoc(S[j]) });
@@ -547,9 +584,14 @@ function bind(node, loc, map, keyMap, stats, path, resolve, gen) {
  * @returns {?{map: WeakMap, stats: Object}} null when the trees are not the same shape
  */
 export function pairCaptured(root, m, provenance = (n) => n) {
+  return drain(pairCapturedSteps(root, m, provenance));
+}
+
+/** The same pairing walk, `yield`ing every `YIELD_EVERY` nodes compared. */
+export function* pairCapturedSteps(root, m, provenance = (n) => n) {
   if (!m.root) return null;
   const found = [];
-  const unresolved = matchCaptured(root, m.root, provenance, found);
+  const unresolved = yield* matchCapturedSteps(root, m.root, provenance, found, { n: 0 });
   if (unresolved < 0) return null;
   const map = new WeakMap();
   // One token for this pass, set on the model and on every bound loc, exactly as `pair`
@@ -567,7 +609,8 @@ export function pairCaptured(root, m, provenance = (n) => n) {
 }
 
 /** @returns {number} unresolved nodes below this pair, or -1 when the two differ at all */
-function matchCaptured(node, loc, provenance, found) {
+function* matchCapturedSteps(node, loc, provenance, found, compared) {
+  if (++compared.n % YIELD_EVERY === 0) yield;
   if (loc.kind === 'text') {
     if (node.nodeType !== 3 || node.data !== loc.value) return -1;
   } else if (loc.kind === 'comment') {
@@ -583,7 +626,7 @@ function matchCaptured(node, loc, provenance, found) {
   const L = capturedKids(node), S = loc.children;
   if (L.length !== S.length) return -1;
   for (let i = 0; i < L.length; i++) {
-    const n = matchCaptured(L[i], S[i], provenance, found);
+    const n = yield* matchCapturedSteps(L[i], S[i], provenance, found, compared);
     if (n < 0) return -1;
     unresolved += n;
   }
@@ -1027,7 +1070,7 @@ function lis(vals) {
 // the right one.
 
 export function verify(rendered, today, liveDocument, clone = null, sourceErrors = null) {
-  return verifyRendered(rendered, today, liveDocument, clone, sourceErrors, false);
+  return drain(verifyRenderedSteps(rendered, today, liveDocument, clone, sourceErrors, false));
 }
 
 /**
@@ -1044,10 +1087,14 @@ export function verify(rendered, today, liveDocument, clone = null, sourceErrors
  * same walk, told to retain what it parsed.
  */
 export function verifyForSave(rendered, today, liveDocument, clone = null, sourceErrors = null) {
-  return verifyRendered(rendered, today, liveDocument, clone, sourceErrors, true);
+  return drain(verifyForSaveSteps(rendered, today, liveDocument, clone, sourceErrors));
+}
+
+export function* verifyForSaveSteps(rendered, today, liveDocument, clone = null, sourceErrors = null) {
+  return yield* verifyRenderedSteps(rendered, today, liveDocument, clone, sourceErrors, true);
 }
 
-function verifyRendered(rendered, today, liveDocument, clone, sourceErrors, retain) {
+export function* verifyRenderedSteps(rendered, today, liveDocument, clone, sourceErrors, retain) {
   const P = new DOMParser();
   const A = P.parseFromString(rendered, 'text/html');
   const outsideA = vOutside(A), outsideLive = vOutside(liveDocument);
@@ -1060,17 +1107,17 @@ function verifyRendered(rendered, today, liveDocument, clone, sourceErrors, reta
   let cloneDiff = null;
   if (clone) {
     at = [];
-    cloneDiff = vDiff(A.documentElement, clone, 'html', at);
+    cloneDiff = yield* vDiffSteps(A.documentElement, clone, 'html', at);
     if (!cloneDiff) {
-      const w = vParseErrors(rendered, sourceErrors, retain);
+      const w = yield* vParseErrorsSteps(rendered, sourceErrors, retain);
       if (w.diff) return { ok: false, diff: w.diff };
       return retain ? withCandidate({ ok: true, diff: null, oracle: 'clone' }, w, rendered, liveDocument)
         : { ok: true, diff: null, oracle: 'clone' };
     }
   }
   const B = P.parseFromString(today, 'text/html');
-  const diff = vDiff(A.documentElement, B.documentElement, 'html');
-  const worse = diff ? null : vParseErrors(rendered, sourceErrors, retain);
+  const diff = yield* vDiffSteps(A.documentElement, B.documentElement, 'html');
+  const worse = diff ? null : yield* vParseErrorsSteps(rendered, sourceErrors, retain);
   if (!diff) {
     if (worse.diff) return { ok: false, diff: worse.diff };
     return retain ? withCandidate({ ok: true, diff: null, oracle: 'today' }, worse, rendered, liveDocument)
@@ -1114,12 +1161,9 @@ export function nodeAt(root, at) {
  * represent, such as a duplicated element, change the tree, and the comparison above
  * is what catches those.
  */
-function vParseErrors(rendered, sourceErrors, retain) {
+export function* vParseErrorsSteps(rendered, sourceErrors, retain) {
   if (!sourceErrors) return { diff: null };
-  const seen = new Map();
-  const doc = parse(rendered, retain
-    ? { sourceCodeLocationInfo: true, onParseError: (e) => seen.set(e.code, (seen.get(e.code) || 0) + 1) }
-    : { onParseError: (e) => seen.set(e.code, (seen.get(e.code) || 0) + 1) });
+  const { document: doc, errors: seen } = yield* parseSteps(rendered, retain ? { sourceCodeLocationInfo: true } : {});
   for (const [code, n] of seen) {
     const was = sourceErrors.get(code) || 0;
     if (n > was) return { diff: `the render introduced parse errors the source does not have: ${code} ${was} -> ${n}` };
@@ -1164,7 +1208,7 @@ function vOutside(doc) {
  * still changes the tree its markup parses to. Recursion terminates because each step
  * compares strictly less markup than the one above it.
  */
-function vNoscript(a, b, path) {
+function* vNoscriptSteps(a, b, path, compared) {
   const P = new DOMParser();
   // Read each side the way it was parsed, which verify fixes, not the node. `a` is always
   // the render reparsed by DOMParser, with scripting off, so its <noscript> text is TEXT,
@@ -1177,7 +1221,7 @@ function vNoscript(a, b, path) {
     const kids = Array.from(el.childNodes);
     return kids.length && kids.every((n) => n.nodeType === 3) ? kids.map((n) => n.data).join('') : el.innerHTML;
   };
-  return vDiff(P.parseFromString(a.innerHTML, 'text/html').body, P.parseFromString(raw(b), 'text/html').body, path + '>#noscript');
+  return yield* vDiffSteps(P.parseFromString(a.innerHTML, 'text/html').body, P.parseFromString(raw(b), 'text/html').body, path + '>#noscript', [], compared);
 }
 function vKids(el) {
   const list = el.localName === 'template' && el.content ? el.content.childNodes : el.childNodes;
@@ -1197,17 +1241,18 @@ function sameAttrsInOrder(a, b) {
   }
   return true;
 }
-function vDiff(a, b, path, at = []) {
+export function* vDiffSteps(a, b, path, at = [], compared = { n: 0 }) {
+  if (++compared.n % YIELD_EVERY === 0) yield;
   if (a.nodeType !== b.nodeType) return path + ': node type ' + a.nodeType + ' vs ' + b.nodeType;
   if (a.nodeType === 3 || a.nodeType === 8) return a.data === b.data ? null : path + ': text ' + JSON.stringify(a.data.slice(0, 60)) + ' vs ' + JSON.stringify(b.data.slice(0, 60));
   if (a.localName !== b.localName || a.namespaceURI !== b.namespaceURI) return path + ': tag ' + a.localName + ' vs ' + b.localName;
   if (!sameAttrsInOrder(a, b) && vAttrs(a) !== vAttrs(b)) return path + ': attrs ' + vAttrs(a) + ' vs ' + vAttrs(b);
-  if (a.localName === 'noscript' && a.namespaceURI === XHTML) return vNoscript(a, b, path);
+  if (a.localName === 'noscript' && a.namespaceURI === XHTML) return yield* vNoscriptSteps(a, b, path, compared);
   const ka = vKids(a), kb = vKids(b);
   if (ka.length !== kb.length) return path + ': ' + ka.length + ' vs ' + kb.length + ' children';
   for (let i = 0; i < ka.length; i++) {
     at.push(i);
-    const d = vDiff(ka[i], kb[i], path + '>' + (ka[i].localName || '#') + '[' + i + ']', at);
+    const d = yield* vDiffSteps(ka[i], kb[i], path + '>' + (ka[i].localName || '#') + '[' + i + ']', at, compared);
     if (d) return d;
     at.pop();
   }

package/src/core/stale-host-notice.js

@@ -68,6 +68,7 @@ function build() {
 
   document.body.appendChild(root);
   place();
+  ui.paintLook(root, { background: ui.TOKENS.surface });
   window.visualViewport?.addEventListener("resize", place);
   window.visualViewport?.addEventListener("scroll", place);
 }

package/src/core/upgrade-run.js

@@ -8,6 +8,8 @@ const MANIFEST_FAILED = "The new version could not be downloaded. Nothing was ch
 const SAVE_FAILED = "The upgrade could not be saved. Nothing was changed.";
 const CONFLICT = "This document changed somewhere else. Reload and try again.";
 const BUSY = "Something else is changing this document. Nothing was changed.";
+const UNDECLARED = "This document does not say which parts are its data, so it cannot be upgraded safely. Nothing was changed.";
+const PAGE_LOST = "The new version has no place for this page's content. Nothing was changed.";
 
 async function digestOf(bytes) {
   const subtle = globalThis.crypto && globalThis.crypto.subtle;
@@ -116,6 +118,26 @@ async function declaredRenames(htmlText) {
   return mod && mod.renames && typeof mod.renames === "object" ? mod.renames : {};
 }
 
+// The page editor's content is its article and the live stores beside it, not values a
+// rules tag can name: the upgrade carries them whole into the new version's article.
+const PAGE_STORE = 'script[clay~="live"][merge]';
+
+function carryPage(doc, afterDoc, article) {
+  const target = afterDoc.querySelector("article[data-page]");
+  if (!target) return null;
+  target.replaceWith(afterDoc.importNode(article, true));
+  for (const store of doc.querySelectorAll(PAGE_STORE)) {
+    const name = store.getAttribute("merge");
+    if (name !== "page" && !name.startsWith("page.")) continue;
+    const copy = afterDoc.importNode(store, true);
+    const existing = [...afterDoc.querySelectorAll(PAGE_STORE)].find((el) => el.getAttribute("merge") === name);
+    if (existing) existing.replaceWith(copy);
+    else afterDoc.querySelector("article[data-page]").after(copy);
+  }
+  const doctype = afterDoc.doctype ? `<!DOCTYPE ${afterDoc.doctype.name}>\n` : "";
+  return doctype + afterDoc.documentElement.outerHTML;
+}
+
 export async function prepare(update, {
   doc = document,
   loc = location,
@@ -187,13 +209,23 @@ export async function prepare(update, {
   }
   const afterDoc = new DOMParser().parseFromString(result.html, "text/html");
   const before = upgrade.extractAll(doc).dataByName;
+  const article = doc.querySelector("article[data-page]");
+  if (!article && !Object.keys(before || {}).length) {
+    return { ok: false, code: "undeclared", message: UNDECLARED };
+  }
+  let html = result.html;
+  if (article) {
+    const carried = carryPage(doc, afterDoc, article);
+    if (!carried) return { ok: false, code: "lost", lost: [], discarded: 0, message: PAGE_LOST };
+    html = carried;
+  }
   const after = upgrade.extractAll(afterDoc).dataByName;
   const lost = lostValues(before, after, renames);
   const discarded = result.summary && result.summary.totals ? result.summary.totals.discarded || 0 : 0;
   if (lost.length || discarded > 0) {
     return { ok: false, code: "lost", lost, discarded, message: lossMessage(lost, discarded) };
   }
-  return { ok: true, html: result.html, version: result.toVersion || latest.version };
+  return { ok: true, html, version: result.toVersion || latest.version };
 }
 
 function lossMessage(lost, discarded) {
@@ -249,7 +281,17 @@ async function applyUnderSlot(update, { doc, loc, fetchFn, clay, reload, replace
     }
   }
 
-  const prepared = await prepare(update, { doc, loc, fetchFn });
+  // An editing tab's live article holds the editor, not the page: the upgrade starts from
+  // the document as a save writes it.
+  let source = doc;
+  if (pageClay.isEditMode && typeof pageClay.getHTML === "function") {
+    try {
+      source = new DOMParser().parseFromString(await pageClay.getHTML(), "text/html");
+    } catch {
+      return { ok: false, code: "failed", message: SAVE_FAILED };
+    }
+  }
+  const prepared = await prepare(update, { doc: source, loc, fetchFn });
   if (!prepared.ok) return prepared;
 
   const save = typeof replace === "function"
@@ -294,11 +336,20 @@ function downloadName(loc) {
   return /\.html?$/i.test(name) ? name : `${name}.html`;
 }
 
-export function downloadCopy({ clay, doc = document, loc = location } = {}) {
-  const getHTML = clay && clay.getHTML;
-  if (typeof getHTML !== "function" || typeof URL === "undefined" || typeof URL.createObjectURL !== "function") return false;
+// A view-mode tab has no save capture, and edits nothing, so the copy is the stored file
+// this upgrade is about to replace. Only a host without version history asks for it.
+export async function pageBytes(clay, { loc = location, fetchFn = (url, init) => fetch(url, init) } = {}) {
+  if (typeof clay.getHTML === "function") return clay.getHTML();
+  const res = await fetchFn(loc.href, { cache: "no-store", credentials: "same-origin" });
+  if (!res.ok) throw new Error(`copy fetch ${res.status}`);
+  return res.text();
+}
+
+export async function downloadCopy({ clay, doc = document, loc = location, fetchFn } = {}) {
+  if (typeof URL === "undefined" || typeof URL.createObjectURL !== "function") return false;
   try {
-    const url = URL.createObjectURL(new Blob([getHTML()], { type: "text/html" }));
+    const bytes = await pageBytes(clay, { loc, fetchFn });
+    const url = URL.createObjectURL(new Blob([bytes], { type: "text/html" }));
     const a = doc.createElement("a");
     a.setAttribute("clay", "editor-ui");
     a.href = url;
@@ -371,8 +422,8 @@ export async function start(update, options = {}) {
   };
 
   if (download) {
-    download.addEventListener("click", () => {
-      if (downloadCopy({ clay, doc, loc: options.loc })) {
+    download.addEventListener("click", async () => {
+      if (await downloadCopy({ clay, doc, loc: options.loc, fetchFn: options.fetchFn })) {
         agree.disabled = false;
         status.textContent = "Your copy was downloaded.";
       } else {

package/src/dom/active-element.js

@@ -0,0 +1,5 @@
+export function deepActiveElement(scope = document) {
+  let active = scope.activeElement;
+  while (active?.shadowRoot?.activeElement) active = active.shadowRoot.activeElement;
+  return active;
+}

package/src/lib/assets.js

@@ -10,6 +10,7 @@ const ASSETS = {
   "highlight/json": () => import("../vendor/hljs-json.vendor.js"),
   "highlight/python": () => import("../vendor/hljs-python.vendor.js"),
   "highlight/xml": () => import("../vendor/hljs-xml.vendor.js"),
+  uimotion: () => import("./uimotion.js"),
 };
 
 export function createAssets(table) {

package/src/lib/slice.js

@@ -0,0 +1,65 @@
+/**
+ * slice.js — a generator that can be run twice two ways.
+ *
+ * Every expensive walk in save verification is written once, as a generator that yields
+ * between whole units of work. `drain` runs it to completion in the calling task, which
+ * is the synchronous function this module had before; `runSliced` resumes it and hands
+ * the event loop back whenever a slice has spent its budget, so the same code can also
+ * run across tasks. There is one implementation, so the two cannot drift apart.
+ *
+ * YIELD POINTS ARE COOPERATIVE, NOT PREEMPTIVE. A generator yields only between units of
+ * work the walk itself chose, so nothing outside sees a half-built model or a half-paired
+ * map: an abort runs the generator's `finally` blocks and returns `{ aborted: true }`
+ * with no result at all, and the caller must treat a partial walk as no walk.
+ *
+ * LAZY. Nothing imports this from the editor's ready path; only source modules that
+ * already load parse5 do.
+ */
+
+/** Run a generator to completion in this task and return its value. */
+export function drain(gen) {
+  let step = gen.next();
+  while (!step.done) step = gen.next();
+  return step.value;
+}
+
+const viaTimer = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+/** A task boundary that works in a hidden tab, where timers are throttled. */
+const viaChannel = () => new Promise((resolve) => {
+  if (typeof MessageChannel !== "function") { viaTimer().then(resolve); return; }
+  const channel = new MessageChannel();
+  channel.port1.onmessage = () => { channel.port1.close(); resolve(); };
+  channel.port2.postMessage(null);
+});
+
+export const defaultYieldTask = () => {
+  const scheduler = globalThis.scheduler;
+  return scheduler?.yield ? scheduler.yield() : viaChannel();
+};
+
+const monotonic = () => (globalThis.performance ? globalThis.performance.now() : Date.now());
+
+/**
+ * Resume a generator, yielding to a task whenever a slice has spent `budgetMs`.
+ *
+ * Resolves with the generator's own return value, rejects with its exception. When
+ * `signal` aborts, the generator is closed (`gen.return()`, so `finally` blocks run) and
+ * the result is `{ aborted: true }`; nothing partial is handed back.
+ */
+export async function runSliced(gen, {
+  budgetMs = 4,
+  signal,
+  now = monotonic,
+  yieldTask = defaultYieldTask,
+} = {}) {
+  let sliceStart = now();
+  for (;;) {
+    if (signal?.aborted) { gen.return(undefined); return { aborted: true }; }
+    const step = gen.next();
+    if (step.done) return step.value;
+    if (now() - sliceStart < budgetMs) continue;
+    await yieldTask();
+    sliceStart = now();
+  }
+}