defuss-morph 0.1.1 → 0.2.0

package/dist/index.cjs

@@ -11,8 +11,7 @@ const CAPTURE_ONLY_EVENTS = /* @__PURE__ */ new Set([
   // Note: focusin/focusout DO bubble, so they're not included here
 ]);
 const elementHandlerMap = /* @__PURE__ */ new WeakMap();
-const bubbleDispatched = /* @__PURE__ */ new WeakMap();
-const captureDispatched = /* @__PURE__ */ new WeakMap();
+const slotListeners = /* @__PURE__ */ new WeakMap();
 const activeDispatches = /* @__PURE__ */ new WeakMap();
 const parseEventPropName = (propName) => {
   if (!propName.startsWith("on")) return null;
@@ -31,147 +30,64 @@ const getOrCreateElementHandlers = (el) => {
   elementHandlerMap.set(el, created);
   return created;
 };
-const getEventPath = (event) => {
-  const composedPath = event.composedPath?.();
-  if (composedPath && composedPath.length > 0) return composedPath;
-  const path = [];
-  let node = event.target;
-  while (node) {
-    path.push(node);
-    const maybeNode = node;
-    if (typeof maybeNode === "object" && maybeNode && "parentNode" in maybeNode) {
-      node = maybeNode.parentNode;
-      continue;
-    }
-    break;
+const runSlot = (target, eventType, phase, event) => {
+  const handler = elementHandlerMap.get(target)?.get(eventType)?.[phase];
+  if (!handler) return;
+  const dispatchKey = `${eventType}:${phase}`;
+  let active = activeDispatches.get(target);
+  if (active?.has(dispatchKey)) return;
+  if (!active) {
+    active = /* @__PURE__ */ new Set();
+    activeDispatches.set(target, active);
+  }
+  active.add(dispatchKey);
+  try {
+    handler.call(target, event);
+  } finally {
+    active.delete(dispatchKey);
   }
-  const doc = event.target?.ownerDocument;
-  if (doc && path[path.length - 1] !== doc) path.push(doc);
-  const win = doc?.defaultView;
-  if (win && path[path.length - 1] !== win) path.push(win);
-  return path;
 };
-const createPhaseHandler = (eventType, phase) => {
-  const dispatched = phase === "capture" ? captureDispatched : bubbleDispatched;
-  return (event) => {
-    const path = getEventPath(event).filter(
-      (t) => typeof t === "object" && t !== null && t.nodeType === 1
-    );
-    const ordered = phase === "capture" ? [...path].reverse() : path;
-    for (const target of ordered) {
-      const handlersByEvent = elementHandlerMap.get(target);
-      if (!handlersByEvent) continue;
-      const entry = handlersByEvent.get(eventType);
-      if (!entry) continue;
-      let targets = dispatched.get(event);
-      if (targets?.has(target)) continue;
-      if (!targets) {
-        targets = /* @__PURE__ */ new WeakSet();
-        dispatched.set(event, targets);
-      }
-      targets.add(target);
-      const dispatchKey = `${eventType}:${phase}`;
-      let activeSet = activeDispatches.get(target);
-      if (activeSet?.has(dispatchKey)) continue;
-      if (!activeSet) {
-        activeSet = /* @__PURE__ */ new Set();
-        activeDispatches.set(target, activeSet);
-      }
-      activeSet.add(dispatchKey);
-      try {
-        if (phase === "capture") {
-          if (entry.capture) {
-            entry.capture.call(target, event);
-            if (event.cancelBubble)
-              return;
-          }
-          if (entry.captureSet) {
-            for (const handler of entry.captureSet) {
-              handler.call(target, event);
-              if (event.cancelBubble)
-                return;
-            }
-          }
-        } else {
-          if (entry.bubble) {
-            entry.bubble.call(target, event);
-            if (event.cancelBubble)
-              return;
-          }
-          if (entry.bubbleSet) {
-            for (const handler of entry.bubbleSet) {
-              handler.call(target, event);
-              if (event.cancelBubble)
-                return;
-            }
-          }
-        }
-      } finally {
-        activeSet.delete(dispatchKey);
-      }
+const setSlot = (target, eventType, phase, entry, handler) => {
+  entry[phase] = handler;
+  const key = `${eventType}:${phase}`;
+  const capture = phase === "capture";
+  let byKey = slotListeners.get(target);
+  const installed = byKey?.get(key);
+  if (handler && !installed) {
+    if (!byKey) {
+      byKey = /* @__PURE__ */ new Map();
+      slotListeners.set(target, byKey);
     }
-  };
-};
-const installedRootListeners = /* @__PURE__ */ new WeakMap();
-const ensureRootListener = (root, eventType) => {
-  const installed = installedRootListeners.get(root) ?? /* @__PURE__ */ new Set();
-  installedRootListeners.set(root, installed);
-  const captureKey = `${eventType}:capture`;
-  if (!installed.has(captureKey)) {
-    root.addEventListener(
-      eventType,
-      createPhaseHandler(eventType, "capture"),
-      true
-    );
-    installed.add(captureKey);
-  }
-  const bubbleKey = `${eventType}:bubble`;
-  if (!installed.has(bubbleKey)) {
-    root.addEventListener(
-      eventType,
-      createPhaseHandler(eventType, "bubble"),
-      false
-    );
-    installed.add(bubbleKey);
+    const trampoline = (event) => runSlot(target, eventType, phase, event);
+    byKey.set(key, trampoline);
+    target.addEventListener(eventType, trampoline, capture);
+  } else if (!handler && installed) {
+    byKey.delete(key);
+    target.removeEventListener(eventType, installed, capture);
   }
 };
-const getEventRoot = (element) => {
-  const root = element.getRootNode();
-  if (root && root.nodeType === 9) {
-    return root;
-  }
-  if (root && root.nodeType === 11 && "host" in root) {
-    return root;
-  }
-  return null;
+const clearPhase = (target, eventType, entry, phase) => {
+  setSlot(target, eventType, phase, entry, void 0);
+  const setKey = phase === "capture" ? "captureSet" : "bubbleSet";
+  for (const handler of entry[setKey] ?? [])
+    target.removeEventListener(eventType, handler, phase === "capture");
+  entry[setKey] = void 0;
 };
 const registerDelegatedEvent = (element, eventType, handler, options = {}) => {
-  const root = getEventRoot(element);
   const capture = options.capture || CAPTURE_ONLY_EVENTS.has(eventType);
-  if (root) {
-    ensureRootListener(root, eventType);
-  } else if (element.ownerDocument) {
-    ensureRootListener(element.ownerDocument, eventType);
-  } else {
-    element.addEventListener(eventType, handler, capture);
-  }
+  const phase = capture ? "capture" : "bubble";
   const byEvent = getOrCreateElementHandlers(element);
   const entry = byEvent.get(eventType) ?? {};
   byEvent.set(eventType, entry);
   if (options.multi) {
-    if (capture) {
-      if (!entry.captureSet) entry.captureSet = /* @__PURE__ */ new Set();
-      entry.captureSet.add(handler);
-    } else {
-      if (!entry.bubbleSet) entry.bubbleSet = /* @__PURE__ */ new Set();
-      entry.bubbleSet.add(handler);
+    const setKey = capture ? "captureSet" : "bubbleSet";
+    const set = entry[setKey] ??= /* @__PURE__ */ new Set();
+    if (!set.has(handler)) {
+      set.add(handler);
+      element.addEventListener(eventType, handler, capture);
     }
   } else {
-    if (capture) {
-      entry.capture = handler;
-    } else {
-      entry.bubble = handler;
-    }
+    setSlot(element, eventType, phase, entry, handler);
   }
 };
 const isEntryEmpty = (entry) => !entry.capture && !entry.bubble && (!entry.captureSet || entry.captureSet.size === 0) && (!entry.bubbleSet || entry.bubbleSet.size === 0);
@@ -181,34 +97,38 @@ const removeDelegatedEvent = (target, eventType, handler, _options = {}) => {
   const entry = byEvent.get(eventType);
   if (!entry) return;
   if (handler) {
-    if (entry.captureSet) {
-      entry.captureSet.delete(handler);
-    }
-    if (entry.bubbleSet) {
-      entry.bubbleSet.delete(handler);
-    }
-    if (entry.capture === handler) {
-      entry.capture = void 0;
-    }
-    if (entry.bubble === handler) {
-      entry.bubble = void 0;
+    for (const phase of ["capture", "bubble"]) {
+      const set = phase === "capture" ? entry.captureSet : entry.bubbleSet;
+      if (set?.delete(handler))
+        target.removeEventListener(eventType, handler, phase === "capture");
+      if (entry[phase] === handler)
+        setSlot(target, eventType, phase, entry, void 0);
     }
-    target.removeEventListener(eventType, handler, true);
-    target.removeEventListener(eventType, handler, false);
   } else {
-    entry.capture = void 0;
-    entry.bubble = void 0;
-    entry.captureSet = void 0;
-    entry.bubbleSet = void 0;
+    clearPhase(target, eventType, entry, "capture");
+    clearPhase(target, eventType, entry, "bubble");
   }
   if (isEntryEmpty(entry)) {
     byEvent.delete(eventType);
   }
 };
+const clearHooks = /* @__PURE__ */ new Set();
+const onClearDelegatedEvents = (hook) => {
+  clearHooks.add(hook);
+  return () => {
+    clearHooks.delete(hook);
+  };
+};
 const clearDelegatedEvents = (target) => {
   const byEvent = elementHandlerMap.get(target);
-  if (!byEvent) return;
-  byEvent.clear();
+  if (byEvent) {
+    for (const [eventType, entry] of byEvent) {
+      clearPhase(target, eventType, entry, "capture");
+      clearPhase(target, eventType, entry, "bubble");
+    }
+    byEvent.clear();
+  }
+  for (const hook of clearHooks) hook(target);
 };
 const clearDelegatedEventsDeep = (root) => {
   clearDelegatedEvents(root);
@@ -246,16 +166,109 @@ const removeDelegatedEventByKey = (element, eventType, phase) => {
   if (!byEvent) return;
   const entry = byEvent.get(eventType);
   if (!entry) return;
-  if (phase === "capture") {
-    entry.capture = void 0;
-    entry.captureSet = void 0;
-  } else {
-    entry.bubble = void 0;
-    entry.bubbleSet = void 0;
-  }
+  clearPhase(element, eventType, entry, phase);
   if (isEntryEmpty(entry)) byEvent.delete(eventType);
 };
 
+const FROM_DOM_MARKER = Symbol("defuss-morph.from-dom");
+const COMMENT_TYPE = "#comment";
+const isCommentVNode = (value) => !!value && typeof value === "object" && value.type === COMMENT_TYPE;
+const HTML_BOOLEAN_ATTRIBUTES = /* @__PURE__ */ new Set([
+  "allowfullscreen",
+  "async",
+  "autofocus",
+  "autoplay",
+  "checked",
+  "controls",
+  "default",
+  "defer",
+  "disabled",
+  "formnovalidate",
+  "hidden",
+  "inert",
+  "ismap",
+  "itemscope",
+  "loop",
+  "multiple",
+  "muted",
+  "nomodule",
+  "novalidate",
+  "open",
+  "playsinline",
+  "readonly",
+  "required",
+  "reversed",
+  "selected"
+]);
+const domAttributeToVNodeValue = (attr) => HTML_BOOLEAN_ATTRIBUTES.has(attr.name.toLowerCase()) ? true : attr.value;
+function parseDOM(input, type, Parser) {
+  return new Parser().parseFromString(input, type);
+}
+function isSVG(input, Parser) {
+  const doc = parseDOM(input, "image/svg+xml", Parser);
+  if (!doc.documentElement) return false;
+  return doc.documentElement.nodeName.toLowerCase() === "svg";
+}
+function isHTML(input, Parser) {
+  const doc = parseDOM(input, "text/html", Parser);
+  return doc.documentElement.querySelectorAll("*").length > 2;
+}
+const isMarkup = (input, Parser) => input.indexOf("<") > -1 && input.indexOf(">") > -1 && (isHTML(input, Parser) || isSVG(input, Parser));
+function renderMarkup(markup, Parser, doc) {
+  const parsed = doc ? doc : parseDOM(markup, getMimeType(markup, Parser), Parser);
+  if (parsed.body) return Array.from(parsed.body.childNodes);
+  return parsed.documentElement ? [parsed.documentElement] : [];
+}
+function getMimeType(input, Parser) {
+  if (isSVG(input, Parser)) {
+    return "image/svg+xml";
+  }
+  return "text/html";
+}
+function domNodeToVNode(node) {
+  if (node.nodeType === 3) {
+    return node.textContent || "";
+  }
+  if (node.nodeType === 1) {
+    const element = node;
+    const attributes = {};
+    for (let i = 0; i < element.attributes.length; i++) {
+      const attr = element.attributes[i];
+      attributes[attr.name] = domAttributeToVNodeValue(attr);
+    }
+    const children = [];
+    for (let i = 0; i < element.childNodes.length; i++) {
+      const childVNode = domNodeToVNode(element.childNodes[i]);
+      children.push(childVNode);
+    }
+    return {
+      type: element.tagName.toLowerCase(),
+      attributes: { ...attributes, [FROM_DOM_MARKER]: true },
+      children
+    };
+  }
+  if (node.nodeType === 8) {
+    return { type: COMMENT_TYPE, value: node.nodeValue ?? "" };
+  }
+  return "";
+}
+const DOCUMENT_START = /^\s*(?:<!--[\s\S]*?-->\s*)*<(?:!doctype|html|head|body)[\s>/]/i;
+function htmlStringToVNodes(html, Parser) {
+  const parser = new Parser();
+  const doc = parser.parseFromString(
+    DOCUMENT_START.test(html) ? html : `<body>${html}`,
+    "text/html"
+  );
+  const vNodes = [];
+  for (let i = 0; i < doc.body.childNodes.length; i++) {
+    const vnode = domNodeToVNode(doc.body.childNodes[i]);
+    if (vnode !== "") {
+      vNodes.push(vnode);
+    }
+  }
+  return vNodes;
+}
+
 const CLASS_ATTRIBUTE_NAME = "class";
 const XLINK_ATTRIBUTE_NAME = "xlink";
 const XMLNS_ATTRIBUTE_NAME = "xmlns";
@@ -329,6 +342,11 @@ const getRenderer = (document) => {
     },
     createElement: (virtualNode, parentDomElement) => {
       let newEl;
+      if (isCommentVNode(virtualNode)) {
+        const comment = document.createComment(virtualNode.value ?? "");
+        parentDomElement?.appendChild(comment);
+        return comment;
+      }
       try {
         if (typeof virtualNode === "function" && virtualNode.constructor.name === "AsyncFunction") {
           newEl = document.createElement("div");
@@ -519,96 +537,6 @@ const getRenderer = (document) => {
   return renderer;
 };
 
-const FROM_DOM_MARKER = Symbol("defuss-morph.from-dom");
-const HTML_BOOLEAN_ATTRIBUTES = /* @__PURE__ */ new Set([
-  "allowfullscreen",
-  "async",
-  "autofocus",
-  "autoplay",
-  "checked",
-  "controls",
-  "default",
-  "defer",
-  "disabled",
-  "formnovalidate",
-  "hidden",
-  "inert",
-  "ismap",
-  "itemscope",
-  "loop",
-  "multiple",
-  "muted",
-  "nomodule",
-  "novalidate",
-  "open",
-  "playsinline",
-  "readonly",
-  "required",
-  "reversed",
-  "selected"
-]);
-const domAttributeToVNodeValue = (attr) => HTML_BOOLEAN_ATTRIBUTES.has(attr.name.toLowerCase()) ? true : attr.value;
-function parseDOM(input, type, Parser) {
-  return new Parser().parseFromString(input, type);
-}
-function isSVG(input, Parser) {
-  const doc = parseDOM(input, "image/svg+xml", Parser);
-  if (!doc.documentElement) return false;
-  return doc.documentElement.nodeName.toLowerCase() === "svg";
-}
-function isHTML(input, Parser) {
-  const doc = parseDOM(input, "text/html", Parser);
-  return doc.documentElement.querySelectorAll("*").length > 2;
-}
-const isMarkup = (input, Parser) => input.indexOf("<") > -1 && input.indexOf(">") > -1 && (isHTML(input, Parser) || isSVG(input, Parser));
-function renderMarkup(markup, Parser, doc) {
-  const parsed = doc ? doc : parseDOM(markup, getMimeType(markup, Parser), Parser);
-  if (parsed.body) return Array.from(parsed.body.childNodes);
-  return parsed.documentElement ? [parsed.documentElement] : [];
-}
-function getMimeType(input, Parser) {
-  if (isSVG(input, Parser)) {
-    return "image/svg+xml";
-  }
-  return "text/html";
-}
-function domNodeToVNode(node) {
-  if (node.nodeType === 3) {
-    return node.textContent || "";
-  }
-  if (node.nodeType === 1) {
-    const element = node;
-    const attributes = {};
-    for (let i = 0; i < element.attributes.length; i++) {
-      const attr = element.attributes[i];
-      attributes[attr.name] = domAttributeToVNodeValue(attr);
-    }
-    const children = [];
-    for (let i = 0; i < element.childNodes.length; i++) {
-      const childVNode = domNodeToVNode(element.childNodes[i]);
-      children.push(childVNode);
-    }
-    return {
-      type: element.tagName.toLowerCase(),
-      attributes: { ...attributes, [FROM_DOM_MARKER]: true },
-      children
-    };
-  }
-  return "";
-}
-function htmlStringToVNodes(html, Parser) {
-  const parser = new Parser();
-  const doc = parser.parseFromString(html, "text/html");
-  const vNodes = [];
-  for (let i = 0; i < doc.body.childNodes.length; i++) {
-    const vnode = domNodeToVNode(doc.body.childNodes[i]);
-    if (vnode !== "") {
-      vNodes.push(vnode);
-    }
-  }
-  return vNodes;
-}
-
 const areDomNodesEqual = (oldNode, newNode) => {
   if (oldNode === newNode) return true;
   if (oldNode.nodeType !== newNode.nodeType) return false;
@@ -625,8 +553,8 @@ const areDomNodesEqual = (oldNode, newNode) => {
       if (oldAttr.value !== newAttrValue) return false;
     }
   }
-  if (oldNode.nodeType === 3) {
-    if (oldNode.textContent !== newNode.textContent) return false;
+  if (oldNode.nodeType === 3 || oldNode.nodeType === 8) {
+    if (oldNode.nodeValue !== newNode.nodeValue) return false;
   }
   return true;
 };
@@ -713,6 +641,7 @@ function areNodeAndChildMatching(domNode, child) {
   if (typeof child === "string" || typeof child === "number" || typeof child === "boolean") {
     return domNode.nodeType === 3;
   }
+  if (isCommentVNode(child)) return domNode.nodeType === 8;
   if (child && typeof child === "object") {
     if (domNode.nodeType !== 1) return false;
     const el = domNode;
@@ -798,6 +727,11 @@ function patchElementInPlace(el, vnode, globals, mergeAttributes = false) {
     return;
   morphDomDirect(el, vnode.children ?? [], globals);
 }
+function replaceNode(old, next) {
+  if (old.nodeType === 1)
+    clearDelegatedEventsDeep(old);
+  old.parentNode?.replaceChild(next, old);
+}
 function morphNode(domNode, child, globals, mergeAttributes = false) {
   if (typeof child === "string" || typeof child === "number" || typeof child === "boolean") {
     const text = String(child);
@@ -806,7 +740,17 @@ function morphNode(domNode, child, globals, mergeAttributes = false) {
       return domNode;
     }
     const next = globals.window.document.createTextNode(text);
-    domNode.parentNode?.replaceChild(next, domNode);
+    replaceNode(domNode, next);
+    return next;
+  }
+  if (isCommentVNode(child)) {
+    const data = child.value ?? "";
+    if (domNode.nodeType === 8) {
+      if (domNode.nodeValue !== data) domNode.nodeValue = data;
+      return domNode;
+    }
+    const next = globals.window.document.createComment(data);
+    replaceNode(domNode, next);
     return next;
   }
   if (child && typeof child === "object") {
@@ -827,13 +771,15 @@ function morphNode(domNode, child, globals, mergeAttributes = false) {
       const created = createDomFromChild(child, globals);
       const first = Array.isArray(created) ? created[0] : created;
       if (!first) return null;
-      el.parentNode?.replaceChild(first, el);
+      replaceNode(el, first);
       handleLifecycleEventsForOnMount(first);
       return first;
     }
     patchElementInPlace(el, child, globals, mergeAttributes);
     return el;
   }
+  if (domNode.nodeType === 1)
+    clearDelegatedEventsDeep(domNode);
   domNode.parentNode?.removeChild(domNode);
   return null;
 }
@@ -888,6 +834,7 @@ function morphDiff(targetRoot, patchItems, globals) {
   }
   for (const item of patchItems) {
     if (typeof item === "string" && item.trim() === "") continue;
+    if (isCommentVNode(item)) continue;
     const key = getVNodeMatchKey(item);
     if (!key) {
       throw new Error(
@@ -1205,6 +1152,7 @@ const morph = (el, newContent, options = {}) => {
 
 exports.CAPTURE_ONLY_EVENTS = CAPTURE_ONLY_EVENTS;
 exports.CLASS_ATTRIBUTE_NAME = CLASS_ATTRIBUTE_NAME;
+exports.COMMENT_TYPE = COMMENT_TYPE;
 exports.DANGEROUSLY_SET_INNER_HTML_ATTRIBUTE = DANGEROUSLY_SET_INNER_HTML_ATTRIBUTE;
 exports.DEFAULT_TRANSITION_CONFIG = DEFAULT_TRANSITION_CONFIG;
 exports.FROM_DOM_MARKER = FROM_DOM_MARKER;
@@ -1223,12 +1171,14 @@ exports.getRenderer = getRenderer;
 exports.getTransitionStyles = getTransitionStyles;
 exports.handleLifecycleEventsForOnMount = handleLifecycleEventsForOnMount;
 exports.htmlStringToVNodes = htmlStringToVNodes;
+exports.isCommentVNode = isCommentVNode;
 exports.isHTML = isHTML;
 exports.isMarkup = isMarkup;
 exports.isSVG = isSVG;
 exports.morph = morph;
 exports.nsMap = nsMap;
 exports.observeUnmount = observeUnmount;
+exports.onClearDelegatedEvents = onClearDelegatedEvents;
 exports.parseDOM = parseDOM;
 exports.parseEventPropName = parseEventPropName;
 exports.performTransition = performTransition;

package/dist/index.d.ts

@@ -28,6 +28,11 @@ interface VNode<A = VNodeAttributes> {
     type?: VNodeType;
     attributes?: A;
     children?: VNodeChildren;
+    /**
+     * Comment data of a `{ type: "#comment" }` VNode (see `COMMENT_TYPE`).
+     * VERIFIED: optional, so defuss core's VNode (no `value`) stays assignable.
+     */
+    value?: string;
     sourceInfo?: unknown;
     /** Original props passed to a function component (set by jsx runtime for SSG hydration). */
     componentProps?: Record<string, any>;
@@ -82,11 +87,23 @@ interface ParsedEventProp {
     eventType: string;
     capture: boolean;
 }
-/** non-bubbling events best handled via capture */
+/**
+ * Events whose handlers are forced into the capture phase, so an ancestor's
+ * handler also sees descendants' events (container onFocus/onBlur). Every
+ * other non-bubbling event reaches only its target's handlers, natively.
+ */
 declare const CAPTURE_ONLY_EVENTS: Set<string>;
 declare const parseEventPropName: (propName: string) => ParsedEventProp | null;
 declare const registerDelegatedEvent: (element: HTMLElement, eventType: string, handler: EventListener, options?: DelegatedEventOptions) => void;
 declare const removeDelegatedEvent: (target: EventTarget, eventType: string, handler?: EventListener, _options?: DelegatedEventOptions) => void;
+/**
+ * Why: listeners a facade attaches natively (defuss-query's on()) live
+ * outside this registry, yet must go whenever morph clears an element
+ * (removal, replacement, clearDelegatedEventsDeep). A hook keeps morph
+ * ignorant of who owns them, instead of morph also tracking native listeners.
+ * Registering the same hook twice is a no-op; returns an unregister function.
+ */
+declare const onClearDelegatedEvents: (hook: (target: EventTarget) => void) => (() => void);
 declare const clearDelegatedEvents: (target: EventTarget) => void;
 /**
  * Clear delegated events for an element and all its descendants.
@@ -130,7 +147,7 @@ declare const getRenderer: (document: Document) => DomAbstractionImpl;
  * 1. Checks for reference equality.
  * 2. Compares node types.
  * 3. For Element nodes, compares tag names and attributes.
- * 4. For Text nodes, compares text content.
+ * 4. For Text and Comment nodes, compares their data.
  */
 declare const areDomNodesEqual: (oldNode: Node, newNode: Node) => boolean;
 /********************************************************
@@ -182,6 +199,17 @@ declare function replaceDomWithVdom(parentElement: Element, newVDOM: RenderInput
  * (same rationale as uncontrolled form-state preservation).
  */
 declare const FROM_DOM_MARKER: unique symbol;
+/**
+ * VNode type of an HTML comment: `{ type: "#comment", value }`.
+ * Why "#comment": it is the DOM's own nodeName for comments and can never
+ * collide with a tag name ("#" is invalid there). The data lives in `value`,
+ * not `children`, so generic tree walkers never mistake it for content.
+ */
+declare const COMMENT_TYPE = "#comment";
+type CommentVNode = VNode & {
+    type: typeof COMMENT_TYPE;
+};
+declare const isCommentVNode: (value: unknown) => value is CommentVNode;
 declare function parseDOM(input: string, type: DOMParserSupportedType, Parser: typeof DOMParser): Document;
 declare function isSVG(input: string, Parser: typeof DOMParser): boolean;
 declare function isHTML(input: string, Parser: typeof DOMParser): boolean;
@@ -229,5 +257,5 @@ interface MorphOptions {
 }
 declare const morph: (el: Element, newContent: RenderInput, options?: MorphOptions) => void | Promise<void>;
 
-export { CAPTURE_ONLY_EVENTS, CLASS_ATTRIBUTE_NAME, DANGEROUSLY_SET_INNER_HTML_ATTRIBUTE, DEFAULT_TRANSITION_CONFIG, FROM_DOM_MARKER, REF_ATTRIBUTE_NAME, XLINK_ATTRIBUTE_NAME, XMLNS_ATTRIBUTE_NAME, applyStyles, areDomNodesEqual, clearDelegatedEvents, clearDelegatedEventsDeep, domNodeToVNode, getMimeType, getRegisteredEventKeys, getRegisteredEventTypes, getRenderer, getTransitionStyles, handleLifecycleEventsForOnMount, htmlStringToVNodes, isHTML, isMarkup, isSVG, morph, nsMap, observeUnmount, parseDOM, parseEventPropName, performTransition, queueCallback, registerDelegatedEvent, removeDelegatedEvent, removeDelegatedEventByKey, renderMarkup, replaceDomWithVdom, resolveGlobals, updateDomWithVdom };
-export type { DefussKey, DelegatedEventOptions, DelegatedPhase, DomAbstractionImpl, Globals, MorphMode, MorphOptions, MountHandler, ParsedEventProp, RefLike, RenderInput, TransitionConfig, TransitionStyles, TransitionType, TransitionsEasing, UnmountHandler, VNode, VNodeAttributes, VNodeChild, VNodeChildren, VNodeType, ValidChild };
+export { CAPTURE_ONLY_EVENTS, CLASS_ATTRIBUTE_NAME, COMMENT_TYPE, DANGEROUSLY_SET_INNER_HTML_ATTRIBUTE, DEFAULT_TRANSITION_CONFIG, FROM_DOM_MARKER, REF_ATTRIBUTE_NAME, XLINK_ATTRIBUTE_NAME, XMLNS_ATTRIBUTE_NAME, applyStyles, areDomNodesEqual, clearDelegatedEvents, clearDelegatedEventsDeep, domNodeToVNode, getMimeType, getRegisteredEventKeys, getRegisteredEventTypes, getRenderer, getTransitionStyles, handleLifecycleEventsForOnMount, htmlStringToVNodes, isCommentVNode, isHTML, isMarkup, isSVG, morph, nsMap, observeUnmount, onClearDelegatedEvents, parseDOM, parseEventPropName, performTransition, queueCallback, registerDelegatedEvent, removeDelegatedEvent, removeDelegatedEventByKey, renderMarkup, replaceDomWithVdom, resolveGlobals, updateDomWithVdom };
+export type { CommentVNode, DefussKey, DelegatedEventOptions, DelegatedPhase, DomAbstractionImpl, Globals, MorphMode, MorphOptions, MountHandler, ParsedEventProp, RefLike, RenderInput, TransitionConfig, TransitionStyles, TransitionType, TransitionsEasing, UnmountHandler, VNode, VNodeAttributes, VNodeChild, VNodeChildren, VNodeType, ValidChild };