@chr33s/solarflare 0.0.10 → 0.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chr33s/solarflare",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "license": "MIT",
   "repository": {
     "type": "git",

package/readme.md

@@ -128,6 +128,7 @@ import { Deferred } from "@chr33s/solarflare/client";
 <meta name="sf:base" content="/" />
 <meta name="sf:scroll-behavior" content="auto" />
 <meta name="sf:view-transitions" content="false" />
+<meta name="sf:skip-node-replacement" content="s-*" />
 
 <!-- performance -->
 <meta name="sf:preconnect" content="https://cdn.example.com" />

package/src/diff-dom-streaming.ts

@@ -1,11 +1,14 @@
 // src: https://github.com/brisa-build/diff-dom-streaming/blob/main/src/index.ts
 
+type ShouldReplaceNode = (node: Node) => boolean;
+
 type Walker = {
   root: Node | null;
   [FIRST_CHILD]: (node: Node) => Promise<Node | null>;
   [NEXT_SIBLING]: (node: Node) => Promise<Node | null>;
   [APPLY_TRANSITION]: (v: () => void) => void;
   [FLUSH_SYNC]: () => void;
+  shouldReplaceNode?: ShouldReplaceNode;
 };
 
 type NextNodeCallback = (node: Node) => void;
@@ -18,6 +21,8 @@ type Options = {
   onChunkProcessed?: () => void;
   /** Apply mutations synchronously instead of batching via requestAnimationFrame. */
   syncMutations?: boolean;
+  /** Elements matching this predicate are atomically replaced instead of diffed. */
+  shouldReplaceNode?: ShouldReplaceNode;
 };
 
 const ELEMENT_TYPE = 1;
@@ -75,6 +80,19 @@ async function updateNode(oldNode: Node, newNode: Node, walker: Walker) {
       });
     }
 
+    // Elements matching shouldReplaceNode are atomically replaced.
+    // Use importNode to create the element in the target document context,
+    // avoiding adoptedCallback from firing on third-party web components.
+    if (walker.shouldReplaceNode?.(oldNode) || walker.shouldReplaceNode?.(newNode)) {
+      return walker[APPLY_TRANSITION](() => {
+        if (oldNode.parentNode) {
+          const doc = oldNode.ownerDocument ?? document;
+          const imported = doc.importNode(newNode, true);
+          oldNode.parentNode.replaceChild(imported, oldNode);
+        }
+      });
+    }
+
     await setChildNodes(oldNode, newNode, walker);
 
     walker[APPLY_TRANSITION](() => {
@@ -147,6 +165,17 @@ function setAttributes(oldAttributes: NamedNodeMap, newAttributes: NamedNodeMap)
   }
 }
 
+/**
+ * Clone a node, using importNode for elements matching shouldReplaceNode
+ * to avoid triggering adoptedCallback on third-party web components.
+ */
+function cloneForDocument(node: Node, targetDoc: Document, walker: Walker): Node {
+  if (walker.shouldReplaceNode?.(node)) {
+    return targetDoc.importNode(node, true);
+  }
+  return node.cloneNode(true);
+}
+
 /**
  * Utility that will nodes childern to match another nodes children.
  */
@@ -237,7 +266,8 @@ async function setChildNodes(oldParent: Node, newParent: Node, walker: Walker) {
       checkOld = oldNode;
       oldNode = oldNode.nextSibling;
       if (getKey(checkOld)) {
-        insertedNode = newNode.cloneNode(true);
+        const targetDoc = oldParent.ownerDocument ?? document;
+        insertedNode = cloneForDocument(newNode, targetDoc, walker);
         if (shouldInsertImmediately(insertedNode!)) {
           flushPendingInsertions();
           walker[APPLY_TRANSITION](() => {
@@ -258,7 +288,8 @@ async function setChildNodes(oldParent: Node, newParent: Node, walker: Walker) {
         await updateNode(checkOld, newNode, walker);
       }
     } else {
-      insertedNode = newNode.cloneNode(true);
+      const targetDoc = oldParent.ownerDocument ?? document;
+      insertedNode = cloneForDocument(newNode, targetDoc, walker);
       if (shouldInsertImmediately(insertedNode!)) {
         flushPendingInsertions();
         walker[APPLY_TRANSITION](() => oldParent.appendChild(insertedNode!));
@@ -426,5 +457,6 @@ async function htmlStreamWalker(stream: ReadableStream, options: Options = {}) {
       }
     },
     [FLUSH_SYNC]: flushMutationsSync,
+    shouldReplaceNode: options.shouldReplaceNode,
   };
 }

package/src/router-stream.ts

@@ -19,6 +19,8 @@ export interface ApplyPatchStreamOptions {
   useTransition: boolean;
   applyMeta: (meta: PatchMeta) => void;
   onChunkProcessed?: () => void;
+  /** Elements matching this predicate are atomically replaced instead of diffed. */
+  shouldReplaceNode?: (node: Node) => boolean;
 }
 
 export async function applyPatchStream(response: Response, options: ApplyPatchStreamOptions) {
@@ -60,6 +62,7 @@ export async function applyPatchStream(response: Response, options: ApplyPatchSt
     transition: options.useTransition,
     syncMutations: !options.useTransition,
     onChunkProcessed: options.onChunkProcessed,
+    shouldReplaceNode: options.shouldReplaceNode,
   });
   await consumeHtml;
 }

package/src/router.ts

@@ -35,11 +35,31 @@ export interface RouterConfig {
   onNotFound?: (url: URL) => void;
   onNavigate?: (match: RouteMatch) => void;
   onError?: (error: Error, url: URL) => void;
+  /** Elements matching this predicate are atomically replaced instead of diffed. */
+  shouldReplaceNode?: (node: Node) => boolean;
 }
 
 /** Subscription callback for route changes. */
 export type RouteSubscriber = (match: RouteMatch | null) => void;
 
+/**
+ * Creates a node matcher from a glob-like pattern.
+ * Supports: "s-*" (prefix), "*-element" (suffix), "my-component" (exact)
+ * Multiple patterns can be comma-separated: "s-*,ui-*"
+ */
+export function createNodeMatcher(pattern: string): (node: Node) => boolean {
+  const patterns = pattern.split(",").map((p) => p.trim().toUpperCase());
+  const matchers = patterns.map((p) => {
+    if (p.endsWith("*")) return (name: string) => name.startsWith(p.slice(0, -1));
+    if (p.startsWith("*")) return (name: string) => name.endsWith(p.slice(1));
+    return (name: string) => name === p;
+  });
+  return (node: Node) => {
+    const name = node.nodeName;
+    return matchers.some((m) => m(name));
+  };
+}
+
 /** Checks if View Transitions API is supported. */
 export function supportsViewTransitions() {
   return typeof document !== "undefined" && "startViewTransition" in document;
@@ -48,7 +68,8 @@ export function supportsViewTransitions() {
 /** Client-side SPA router using Navigation API and View Transitions. */
 export class Router {
   #routes: Route[] = [];
-  #config: Required<RouterConfig>;
+  #config: Required<Omit<RouterConfig, "shouldReplaceNode">> &
+    Pick<RouterConfig, "shouldReplaceNode">;
   #started = false;
   #cleanupFns: (() => void)[] = [];
   #inflightAbort: AbortController | null = null;
@@ -72,6 +93,12 @@ export class Router {
     const metaBase = getMeta("base");
     const metaViewTransitions = getMeta<"true" | "false">("view-transitions");
     const metaScrollBehavior = getMeta<"auto" | "smooth" | "instant">("scroll-behavior");
+    const metaSkipNodeReplace = getMeta("skip-node-replacement");
+
+    // Convert glob pattern (e.g., "s-*") to shouldReplaceNode predicate
+    const shouldReplaceNode =
+      config.shouldReplaceNode ??
+      (metaSkipNodeReplace ? createNodeMatcher(metaSkipNodeReplace) : undefined);
 
     this.#config = {
       base: config.base ?? metaBase ?? manifest.base ?? "",
@@ -84,6 +111,7 @@ export class Router {
         ((error, url) => {
           console.error(`[solarflare] Navigation error for ${url.href}:`, error);
         }),
+      shouldReplaceNode,
     };
 
     this.params = computed(() => this.current.value?.params ?? {});
@@ -293,6 +321,7 @@ export class Router {
       await applyPatchStream(response, {
         useTransition,
         applyMeta,
+        shouldReplaceNode: this.#config.shouldReplaceNode,
         onChunkProcessed: () => {
           if (didScroll) return;
           didScroll = true;