tungsten 0.3.2 → 0.3.4

package/dist/update/integrateUpdateVdom.js

@@ -23,6 +23,58 @@ import { setCurrentComponent } from 'tungsten/hooks/setCurrentComponent.js';
 import { clearCurrentComponent } from 'tungsten/hooks/clearCurrentComponent.js';
 import { isDev } from "../isDev.js";
 import { $original } from "../componentProxyHandlers.js";
+import { booleanAttributeValue } from "../booleanAttributeValue.js";
+import { propsAreEqual } from "../propsAreEqual.js";
+import { markRendered, refreshTracing, renderedAt, trace, tracing } from "../stateTracking.js";
+import { beginMountScope, discardPendingMounts, endMountScope, queueMount } from "./pendingMounts.js";
+/**
+ * How many dom nodes each element's rendered content currently occupies, recorded on
+ * every real update. When an update is skipped for unchanged props the child's dom is
+ * untouched, so the count still holds -- and the dom pointer can be advanced without
+ * measuring the region, which would mean scanning parent.childNodes.
+ */
+const skippedNodesLength = new WeakMap();
+const reconcileStats = new Map();
+let reconcileDepth = 0;
+function bucket(name) {
+  const existing = reconcileStats.get(name);
+  if (existing !== undefined) return existing;
+  const created = {
+    n: 0,
+    ms: 0
+  };
+  reconcileStats.set(name, created);
+  return created;
+}
+/** times `work` into `name` when tracing, and is a plain call-through when not */
+async function timed(name, work) {
+  if (!tracing()) return work();
+  const b = bucket(name);
+  const start = performance.now();
+  try {
+    return await work();
+  } finally {
+    b.n++;
+    b.ms += performance.now() - start;
+  }
+}
+function timedSync(name, work) {
+  if (!tracing()) return work();
+  const b = bucket(name);
+  const start = performance.now();
+  try {
+    return work();
+  } finally {
+    b.n++;
+    b.ms += performance.now() - start;
+  }
+}
+function reportReconcileStats(elementName) {
+  if (reconcileStats.size === 0) return;
+  const parts = [...reconcileStats.entries()].sort(([, a], [, b]) => b.ms - a.ms).map(([name, b]) => `${name} ${b.ms.toFixed(1)}ms/${b.n}`);
+  trace('RECONCILE', elementName, parts.join('  '));
+  reconcileStats.clear();
+}
 function debug(...texts) {
   //console.log(...texts)
   //console.log(getStackTrace().split('\n')[2])
@@ -32,6 +84,15 @@ const timing = false; // eslint-disable-line no-type-assertion/no-type-assertion
 export async function integrateElementUpdateVdom(element, newContent) {
   let startTime = 0;
   if (timing) startTime = new Date().getMilliseconds();
+  // Only the outermost call reports, so nested components roll up into one line per
+  // update rather than one per component. Depth is restored from the value captured on
+  // entry rather than decremented, so a throw in a nested call cannot leave the counter
+  // stuck above zero and silently suppress every later report.
+  const reconcileEntryDepth = ++reconcileDepth;
+  if (reconcileEntryDepth === 1) refreshTracing();
+  // anything created during this update mounts detached and is attached before the
+  // outermost integrate returns, so its mount hooks wait until then
+  beginMountScope();
   debug(`integrateElementUpdateVdom`, element);
   debug(`integrateElementUpdateVdom`, newContent);
   //console.log('***** integrateElementUpdateVdom', element.constructor.name, '*****')
@@ -96,11 +157,17 @@ export async function integrateElementUpdateVdom(element, newContent) {
   //console.log('firstElement', element.__domRegion?.firstElement)
   //console.log('lastElement', element.__domRegion?.lastElement)
   //console.log('Current Content after update for element', element.constructor.name, 'is', element.__currentContent)
-  const newPositionOfFirstElement = domRegion.positionOfFirst();
-  const newPositionOfLastElement = domRegion.positionOfLast();
+  // These were just written by updateByIndexes() immediately above, so the region's
+  // bounds are already known -- asking positionOfFirst()/positionOfLast() would
+  // indexOf them back out of parent.childNodes, an O(n) scan per component update.
+  const newPositionOfFirstElement = previousPositionOfFirstElement;
+  const newPositionOfLastElement = domPointer.index - 1;
   const newNodesLength = newPositionOfFirstElement >= 0 ? 1 + newPositionOfLastElement - newPositionOfFirstElement : 0;
   //console.log('finished updating element. ', element.constructor.name, ' El positions:', newPositionOfFirstElement, newPositionOfLastElement)
   if (timing) out(`Updated ${element.constructor.name} in ${new Date().getMilliseconds() - startTime}ms`);
+  reconcileDepth = reconcileEntryDepth - 1;
+  if (reconcileDepth === 0 && tracing()) reportReconcileStats(element.constructor.name);
+  endMountScope();
   // newNodesLength previousNodesLength
   return {
     renderedContent: renderedTree,
@@ -118,7 +185,9 @@ function getKeyedOldChildren(array) {
   }
   return keyedChildren;
 }
-async function applyUpdate({
+// oldNode: $contentNull reconciles as a pure create (falls through to createNode()) - used by
+// hydrate.tsx's CSR branch for <body>.
+export async function applyUpdate({
   tungstenElement,
   instance,
   newNode,
@@ -146,7 +215,7 @@ async function applyUpdate({
       //oldNode
       //console.log('array update', newNode)
       //console.log('old array', oldNode)
-      const keyedOldChildren = getKeyedOldChildren(oldNode);
+      const keyedOldChildren = timedSync('indexOldKeys', () => getKeyedOldChildren(oldNode));
       const tempOldChildren = [...oldNode];
       if (Object.keys(keyedOldChildren).length > 0) {
         //console.log('handling a keyed array')
@@ -195,7 +264,7 @@ async function applyUpdate({
             // create a throwaway DomPointer because we are going to manage our DomPointer differently
             const tempDomPointer = new DomPointer(domPointer.parent, domPointer.index);
             // update
-            renderedContent = await applyUpdate({
+            const updated = await timed('keyedUpdate', () => applyUpdate({
               tungstenElement,
               instance,
               newNode: childNode,
@@ -203,10 +272,11 @@ async function applyUpdate({
               domRegion,
               domPointer: tempDomPointer,
               parentNode
-            });
+            }));
+            renderedContent = updated;
             // move
             //console.log('moving the keyed item', childNode[$key])
-            moveRenderedContent(renderedContent, domPointer);
+            timedSync('keyedMove', () => moveRenderedContent(updated, domPointer));
             // delete oldChild from temp list
             delete tempOldChildren[oldChildIndex];
           } else {
@@ -218,7 +288,7 @@ async function applyUpdate({
               //console.log('update/replace a non keyed item', _nki)
               //throwError('b', 'b')
               // update/replace as required
-              renderedContent = await applyUpdate({
+              const updated = await timed('unkeyedUpdate', () => applyUpdate({
                 tungstenElement,
                 instance,
                 newNode: childNode,
@@ -226,11 +296,12 @@ async function applyUpdate({
                 domRegion,
                 domPointer: tempDomPointer,
                 parentNode
-              });
+              }));
+              renderedContent = updated;
               // move -- we need to move it, because we may have removed or inserted elements
               // pushing the original out of place
               //console.log('moving the non keyed item', _nki)
-              moveRenderedContent(renderedContent, domPointer);
+              timedSync('unkeyedMove', () => moveRenderedContent(updated, domPointer));
               // remove replaced node from list
               delete tempOldChildren[i];
             } else {
@@ -238,13 +309,13 @@ async function applyUpdate({
               //console.log('dp', domPointer)
               //throwError('c', 'c')
               // create
-              renderedContent = await createNode({
+              renderedContent = await timed('create', () => createNode({
                 tungstenElement,
                 instance,
                 newNode: childNode,
                 domPointer,
                 parentNode
-              });
+              }));
             }
           }
           renderedNodes.push(renderedContent);
@@ -255,7 +326,7 @@ async function applyUpdate({
         for (const oldChild of tempOldChildren) {
           if (oldChild) {
             //console.log('deleting old child', oldChild)
-            deleteNodeIfRendered(oldChild);
+            timedSync('trim', () => deleteNodeIfRendered(oldChild));
           }
         }
         return renderedNodes;
@@ -487,17 +558,26 @@ function moveRenderedContent(renderedContent, domPointer) {
 }
 function moveDomNode(domNode, domPointer) {
   //console.log('moving domNode', domNode)
-  if (domPointer.positionOf(domNode) !== domPointer.index) {
+  // O(1) position check. positionOf() is Array.indexOf over parent.childNodes, which
+  // is O(n) in the sibling count -- and this runs once per node per update, making a
+  // keyed array update O(n^2): 20k rows cost ~400M comparisons even when nothing moved.
+  // Reading the node already at `index` answers the same question, and differs from
+  // domNode in exactly the cases indexOf(domNode) !== index did: the node is elsewhere,
+  // is not a child at all (indexOf -1), or index is past the end (undefined).
+  // one live-NodeList read, reused as the insertBefore reference below -- see
+  // DomPointer.insert() for why these reads are worth counting
+  const reference = domPointer.parent.childNodes[domPointer.index]; // eslint-disable-line no-type-assertion/no-type-assertion -- indexing past the end gives undefined, which the DOM types do not model
+  if (reference !== domNode) {
     //console.log('document.activeElement', document.activeElement, domNode ==  document.activeElement,  domNode ===  document.activeElement)
     const ownerDocument = domNode.ownerDocument;
     const hasFocus = domNode === ownerDocument.activeElement;
     const activeElement = ownerDocument.activeElement;
-    if (domPointer.index >= domPointer.parent.childNodes.length) {
+    if (reference === undefined) {
       //console.log('appending', domNode)
       domPointer.parent.appendChild(domNode);
     } else {
       //console.log('inserting at', domPointer.index, domNode)
-      domPointer.parent.insertBefore(domNode, domPointer.parent.childNodes[domPointer.index]);
+      domPointer.parent.insertBefore(domNode, reference);
     }
     //console.log('had focus', hasFocus)
     if (hasFocus) domNode.focus();
@@ -595,12 +675,7 @@ function createComment({
   debug('-createComment');
   //console.log('createComment', text)
   const comment = documentFromParent(domPointer.parent).createComment(text);
-  if (domPointer.index >= domPointer.parent.childNodes.length) {
-    domPointer.parent.appendChild(comment);
-  } else {
-    domPointer.parent.insertBefore(comment, domPointer.parent.childNodes[domPointer.index]);
-  }
-  domPointer.increment();
+  domPointer.insert(comment);
   return comment;
 }
 export function processHtmlNode(node, parentNode) {
@@ -741,15 +816,10 @@ function createLiteral(value, domPointer) {
   debug('-createLiteral:', value);
   //const textNode = createTextElement(String(value), domPointer)
   const text = String(value);
-  debug('dom parent', domPointer.parent);
-  debug('dom index', domPointer.index);
+  if (isDev) debug('dom parent', domPointer.parent);
+  if (isDev) debug('dom index', domPointer.index);
   const textNode = documentFromParent(domPointer.parent).createTextNode(text);
-  if (domPointer.parent.childNodes.length === domPointer.index) {
-    domPointer.parent.appendChild(textNode);
-  } else {
-    domPointer.parent.insertBefore(textNode, domPointer.parent.childNodes[domPointer.index]);
-  }
-  domPointer.increment();
+  domPointer.insert(textNode);
   //domPointer.increment()
   return typeof value === 'string' ? {
     [$type]: $string,
@@ -769,7 +839,8 @@ async function createHtmlElement(tungstenElement, instance, node, domPointer, pa
   processHtmlNode(node, parentNode);
   debug('-createHtmlElement', node);
   const htmlEl = documentFromParent(domPointer.parent).createElement(node[$type]);
-  addAttributes(tungstenElement, instance, node, htmlEl);
+  const extendableEl = htmlEl; // eslint-disable-line no-type-assertion/no-type-assertion -- attributes are attached to the element later
+  addAttributes(tungstenElement, instance, node, extendableEl);
   if (node[$type] === 'head') {
     for (const el of instance.persistentHeadChildren) {
       htmlEl.appendChild(el.cloneNode(true));
@@ -780,21 +851,19 @@ async function createHtmlElement(tungstenElement, instance, node, domPointer, pa
   if ('ref' in node[$props]) {
     node[$props].ref.current = htmlEl;
   }
-  debug('dom parent', domPointer.parent);
-  debug('dom parent children length', domPointer.parent.childNodes.length);
-  debug('domPointer.index', domPointer.index);
-  if (domPointer.index >= domPointer.parent.childNodes.length) {
-    domPointer.parent.appendChild(htmlEl);
-  } else {
-    debug('new html el', htmlEl);
-    debug('insert before', domPointer.parent.childNodes[domPointer.index]);
-    domPointer.parent.insertBefore(htmlEl, domPointer.parent.childNodes[domPointer.index]);
-    debug('created el', domPointer.get());
-  }
-  domPointer.increment();
+  // debug() has a commented-out body, but its arguments are still evaluated -- and these
+  // ones read the live NodeList, which walks the child list. Behind `if (isDev)` they
+  // short-circuit in dev and are removed from the production bundle entirely.
+  if (isDev) debug('dom parent', domPointer.parent);
+  if (isDev) debug('dom parent children length', domPointer.parent.childNodes.length);
+  if (isDev) debug('domPointer.index', domPointer.index);
+  if (isDev) debug('new html el', htmlEl);
   //!!!! node.domElement = el
   if (IsHTMLElement(domPointer.parent)) debug('***', node[$type], 'html created', htmlEl);
-  // children
+  // children -- built while htmlEl is still detached, then the finished subtree is
+  // inserted once below. Appending into an element that is already in the document
+  // makes the browser invalidate style and layout on every child; off document it
+  // does none of that until the subtree lands.
   const innerHtml = innerHtmlFromProps(node[$type], node[$props], validChildren(node[$props].children));
   let renderedChildren;
   if (innerHtml !== null) {
@@ -816,6 +885,8 @@ async function createHtmlElement(tungstenElement, instance, node, domPointer, pa
       htmlEl.value = String(node[$props].value);
     }
   }
+  // the subtree is complete, so attach it in one operation
+  domPointer.insert(htmlEl);
   return {
     ...node,
     domNode: htmlEl,
@@ -849,7 +920,8 @@ function addAttributes(tungstenElement, instance, node, domNode) {
       //console.log('add attr', key, attributes[key])
       if (typeof attributes[key] === 'boolean') {
         //console.log('bool attr', attributes[key])
-        if (attributes[key]) domNode.setAttribute(key, '');
+        const attrValue = booleanAttributeValue(key, attributes[key]);
+        if (attrValue !== null) domNode.setAttribute(key, attrValue);
       } else if (attributes[key] !== undefined && attributes[key] !== null) {
         //console.log('string attr', String(attributes[key]))
         domNode.setAttribute(key, String(attributes[key]));
@@ -913,7 +985,8 @@ function updateAttributes(tungstenElement, instance, node, oldNode, domNodeHTMLE
         domNode.value = String(newAttributes[key]);
       } else {
         if (typeof newAttributes[key] === 'boolean') {
-          if (newAttributes[key]) domNode.setAttribute(key, '');else removeAttribute(domNode, key);
+          const attrValue = booleanAttributeValue(key, newAttributes[key]);
+          if (attrValue !== null) domNode.setAttribute(key, attrValue);else removeAttribute(domNode, key);
         } else if (newAttributes[key] === undefined || newAttributes[key] === null) {
           removeAttribute(domNode, key);
         } else {
@@ -1004,6 +1077,7 @@ function processAttributes(node) {
     } else {
       attributes.style = attributes.css;
     }
+    delete attributes.css;
   }
   return attributes;
 }
@@ -1033,6 +1107,7 @@ export async function createTungstenRootComponent(RootComponent, props, routePar
     instance,
     parentElement: null
   });
+  beginMountScope();
   try {
     await component.__init();
     const content = await component.__initialContent();
@@ -1054,13 +1129,16 @@ export async function createTungstenRootComponent(RootComponent, props, routePar
     });
     component.__domRegion = new DomRegion(container, domStartIndex, domPointer.index - domStartIndex);
     component.__currentContent = renderedContent;
-    component.__didMount();
+    queueMount(() => component.__didMount());
+    // everything this root created is attached by now, so the queued hooks can run
+    endMountScope();
     return {
       component,
       openingComment,
       closingComment
     };
   } catch (error) {
+    discardPendingMounts();
     component.__delete();
     while (container.childNodes.length > domStartIndex) {
       container.removeChild(container.childNodes[domStartIndex]);
@@ -1135,7 +1213,7 @@ async function createTungstenClassComponent(parent, instance, node, domPointer)
   debug(`[${c}]`, '&& dom region last element', element.__domRegion.lastElement);
   //console.log('created dom region', element.__domRegion)
   element.__currentContent = renderedContent;
-  element.__didMount();
+  queueMount(() => element.__didMount());
   const wrapper = {
     ...node,
     element,
@@ -1179,11 +1257,14 @@ async function createTungstenFunctionComponent(parent, instance, node, domPointe
   });
   //const renderedContent: RenderedContentNode = await integrateNode({ node: content, domRegion: null, domPointer, parent: element, instance })
   const domLength = domPointer.index - domStartIndex;
-  debug(`[${x}]`, '&& Continuing create FC', node);
-  debug(`[${x}]`, '&& domPointer.parent', domPointer.parent);
-  debug(`[${x}]`, '&& dom start index', domStartIndex);
-  debug(`[${x}]`, '&& dom length', domLength);
-  debug(`[${x}]`, '&& dom pointer children', domPointer.parent.childNodes);
+  if (isDev) {
+    // these run once per created component, and each allocates a template literal
+    debug(`[${x}]`, '&& Continuing create FC', node);
+    debug(`[${x}]`, '&& domPointer.parent', domPointer.parent);
+    debug(`[${x}]`, '&& dom start index', domStartIndex);
+    debug(`[${x}]`, '&& dom length', domLength);
+    debug(`[${x}]`, '&& dom pointer children', domPointer.parent.childNodes);
+  }
   //console.log('new dom region when creating func comp', node[$type].name, domPointer.parent)
   element.__domRegion = new DomRegion(domPointer.parent, domStartIndex, domLength);
   //console.log('&& dom region first element', element.__domRegion.firstElement)
@@ -1205,6 +1286,27 @@ async function updateClassComponent({
 }) {
   //console.log('-updateClassComponent', newNode)
   const element = oldNode.element;
+  // element.props still holds what was last rendered, so this asks "has anything
+  // changed since we last rendered?". If not, the child's dom is already correct and
+  // re-rendering it is wasted work -- which for a large list child means reconciling
+  // every row so an unrelated sibling can update. componentDidUpdate deliberately does
+  // not fire: the component did not update.
+  if (propsAreEqual(element.props, newNode[$props], renderedAt(element))) {
+    if (tracing()) trace('SKIP', element.constructor.name, '(props unchanged since tick', renderedAt(element), ')');
+    // the dom is current for these props, so the baseline moves with it -- otherwise a
+    // component that only ever skips keeps comparing against its mount tick, and the
+    // first shared object it is handed always looks changed
+    markRendered(element);
+    // the weakmap is only written by a previous update, so on the first update after
+    // mount fall back to measuring the element's own region -- its index caches were
+    // seeded when it was created, so this is not a scan either
+    const cachedLength = skippedNodesLength.get(element) ?? element.__domRegion?.length();
+    if (cachedLength !== undefined) {
+      domPointer.increment(cachedLength);
+      return oldNode;
+    }
+  }
+  if (tracing()) trace('RENDER', element.constructor.name, '(since tick', renderedAt(element), ')');
   element.props = newNode[$props];
   debug('update class component', newNode);
   //console.log('update class component', newNode)
@@ -1213,6 +1315,8 @@ async function updateClassComponent({
   //console.log('domPointer children', [...domPointer.parent.childNodes])
   //throwError('','')
   const updateResult = await element.__update();
+  markRendered(element);
+  skippedNodesLength.set(element, updateResult.nodesLength);
   domPointer.increment(updateResult.nodesLength); // bump the dom pointer index forward by the number of nodes within that element's content
   const wrapper = {
     ...newNode,
@@ -1231,8 +1335,19 @@ async function updateFunctionComponent({
   // this func does not seem to be updating the dom pointer index
   //console.log('updateFunctionComponent')
   const standIn = oldNode.element;
+  // see updateClassComponent: unchanged props mean the rendered dom is already correct
+  if (propsAreEqual(standIn.props, newNode[$props], renderedAt(standIn))) {
+    markRendered(standIn); // see updateClassComponent
+    const cachedLength = skippedNodesLength.get(standIn) ?? standIn.__domRegion?.length();
+    if (cachedLength !== undefined) {
+      domPointer.increment(cachedLength);
+      return oldNode;
+    }
+  }
   standIn.props = newNode[$props];
   const updateResult = await standIn.update();
+  markRendered(standIn);
+  skippedNodesLength.set(standIn, updateResult.nodesLength);
   domPointer.increment(updateResult.nodesLength); // bump the dom pointer index forward by the number of nodes within that element's content
   const wrapper = {
     ...newNode,
@@ -1331,7 +1446,7 @@ export async function hotSwapClassComponent(oldElement, NewType) {
   });
   newElement.__domRegion = new DomRegion(parent, domStartIndex, domPointer.index - domStartIndex);
   newElement.__currentContent = renderedContent;
-  newElement.__didMount();
+  queueMount(() => newElement.__didMount());
   wrapper.element = newElement;
   wrapper[$props] = newElement.props;
   newElement.__renderedNode = wrapper;

package/dist/update/pendingMounts.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Defers mount hooks until the dom they belong to is in the document.
+ *
+ * Elements are assembled off document and inserted once their subtree is complete, which
+ * is what React, Vue and Svelte all do -- appending into an already-attached element makes
+ * the browser invalidate style and layout on every child. The cost is that a component
+ * created part way through that build would see a detached node in componentDidMount, where
+ * getBoundingClientRect returns zeros and .focus() does nothing, failing silently rather
+ * than throwing.
+ *
+ * So creation opens a scope, mount hooks queue inside it, and the scope's owner flushes
+ * them once everything it created has been attached. Hooks are queued as their components
+ * finish creating -- children before parents -- and the queue drains in that order, so a
+ * parent's hook can still rely on its children having mounted.
+ */
+export declare function beginMountScope(): void;
+/**
+ * Runs `hook` when the current scope closes, or immediately if there is no scope -- the
+ * dom is already attached in that case, so there is nothing to wait for.
+ */
+export declare function queueMount(hook: () => void): void;
+export declare function endMountScope(): void;
+/** drops anything still queued -- used when a create pass fails and unwinds */
+export declare function discardPendingMounts(): void;
+//# sourceMappingURL=pendingMounts.d.ts.map

package/dist/update/pendingMounts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pendingMounts.d.ts","sourceRoot":"","sources":["../../src/update/pendingMounts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,IAAI,GAAG,IAAI,CAMjD;AAED,wBAAgB,aAAa,IAAI,IAAI,CAgBpC;AAED,+EAA+E;AAC/E,wBAAgB,oBAAoB,IAAI,IAAI,CAI3C"}

package/dist/update/pendingMounts.js

@@ -0,0 +1,55 @@
+/**
+ * Defers mount hooks until the dom they belong to is in the document.
+ *
+ * Elements are assembled off document and inserted once their subtree is complete, which
+ * is what React, Vue and Svelte all do -- appending into an already-attached element makes
+ * the browser invalidate style and layout on every child. The cost is that a component
+ * created part way through that build would see a detached node in componentDidMount, where
+ * getBoundingClientRect returns zeros and .focus() does nothing, failing silently rather
+ * than throwing.
+ *
+ * So creation opens a scope, mount hooks queue inside it, and the scope's owner flushes
+ * them once everything it created has been attached. Hooks are queued as their components
+ * finish creating -- children before parents -- and the queue drains in that order, so a
+ * parent's hook can still rely on its children having mounted.
+ */
+const pending = [];
+let depth = 0;
+let flushing = false;
+export function beginMountScope() {
+  depth++;
+}
+/**
+ * Runs `hook` when the current scope closes, or immediately if there is no scope -- the
+ * dom is already attached in that case, so there is nothing to wait for.
+ */
+export function queueMount(hook) {
+  if (depth === 0) {
+    hook();
+    return;
+  }
+  pending.push(hook);
+}
+export function endMountScope() {
+  if (depth > 0) depth--;
+  if (depth > 0) return;
+  // A hook may create more components, which opens and closes further scopes. Draining
+  // from the front means anything they queue joins the end of this same pass rather than
+  // starting a nested one.
+  if (flushing) return;
+  flushing = true;
+  try {
+    while (pending.length > 0) {
+      const hook = pending.shift();
+      if (hook !== undefined) hook();
+    }
+  } finally {
+    flushing = false;
+  }
+}
+/** drops anything still queued -- used when a create pass fails and unwinds */
+export function discardPendingMounts() {
+  pending.length = 0;
+  depth = 0;
+  flushing = false;
+}

package/dist/warnOnFrameworkChange.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"warnOnFrameworkChange.d.ts","sourceRoot":"","sources":["../src/warnOnFrameworkChange.ts"],"names":[],"mappings":"AASA,wBAAgB,qBAAqB,IAAI,IAAI,CAmB5C"}
+{"version":3,"file":"warnOnFrameworkChange.d.ts","sourceRoot":"","sources":["../src/warnOnFrameworkChange.ts"],"names":[],"mappings":"AAcA,wBAAgB,qBAAqB,IAAI,IAAI,CAc5C"}

package/dist/warnOnFrameworkChange.js

@@ -6,11 +6,15 @@ import { cliWarn } from "./cliOutput.js";
 // cache can't be invalidated at runtime, so an already-running dev server can't pick up a
 // change to the tungsten package itself (e.g. a linked/workspace copy being rebuilt) without a
 // full process restart - this just tells the developer that's needed, rather than attempting it.
+//
+// Watches a single marker file (dist/.build-complete) rather than all of dist - tungsten's own
+// build scripts touch it as their last step (see scripts/writeBuildMarker.mjs), so one file
+// covers every file a build could have changed without chokidar scanning the whole tree. Watch
+// mode (build-babel --watch) does not yet write it on each cycle, only the one-shot builds do.
 export function warnOnFrameworkChange() {
   const frameworkDistDir = join(getFrameworkDir(), 'dist');
-  // debounced so one rebuild (many files touched at once) produces one warning, not one per file
-  let debounceTimer = null;
-  const watcher = chokidar.watch(frameworkDistDir, {
+  const buildMarkerPath = join(frameworkDistDir, '.build-complete');
+  const watcher = chokidar.watch(buildMarkerPath, {
     ignoreInitial: true,
     awaitWriteFinish: {
       stabilityThreshold: 200,
@@ -18,10 +22,6 @@ export function warnOnFrameworkChange() {
     }
   });
   watcher.on('all', () => {
-    if (debounceTimer !== null) clearTimeout(debounceTimer);
-    debounceTimer = setTimeout(() => {
-      debounceTimer = null;
-      cliWarn(`tungsten framework files changed (${frameworkDistDir}) - restart the dev server` + ` to pick up the change.`);
-    }, 300);
+    cliWarn(`tungsten framework files changed (${frameworkDistDir}) - restart the dev server` + ` to pick up the change.`);
   });
 }