@cocreate/server-side-render 1.12.8 → 1.14.1

package/.github/workflows/automated.yml

@@ -1,8 +1,10 @@
 name: Automated Workflow
+
 on:
   push:
     branches:
       - master
+
 jobs:
   about:
     runs-on: ubuntu-latest
@@ -18,52 +20,37 @@ jobs:
         with:
           direction: overwrite-github
           githubToken: "${{ secrets.GITHUB }}"
+
   release:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Required so semantic-release can trace git tags/history
+
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 22 # Required for the latest semantic-release plugins
-      - name: Semantic Release
-        uses: cycjimmy/semantic-release-action@v4 # Update to v4 for better Node 20+ support
-        id: semantic
-        with:
-          extra_plugins: |
-            @semantic-release/changelog
+          node-version: 22
+
+      - name: Install Semantic Release & Plugins
+        # Installs semantic-release and its plugins on the runner
+        run: |
+          npm install -g semantic-release \
+            @semantic-release/changelog \
+            @semantic-release/npm \
+            @semantic-release/github \
             @semantic-release/git
-            @semantic-release/github
+
+      - name: Run Semantic Release (Native)
+        id: semantic
+        # This will automatically pick up your export default config file in the repository root
+        run: npx semantic-release
         env:
-          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}" # Use the built-in token if possible
+          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
           NPM_TOKEN: "${{ secrets.NPM_TOKEN }}"
+
     outputs:
       new_release_published: "${{ steps.semantic.outputs.new_release_published }}"
-      new_release_version: "${{ steps.semantic.outputs.new_release_version }}"
-  upload:
-    runs-on: ubuntu-latest
-    needs: release
-    if: needs.release.outputs.new_release_published == 'true'
-    env:
-      VERSION: "${{ needs.release.outputs.new_release_version }}"
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-      - name: Setup Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: 16
-      - name: Set npm registry auth
-        run: echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > ~/.npmrc
-      - name: Install dependencies
-        run: yarn install
-      
-      - name: Set Environment Variables
-        run: |
-          echo "organization_id=${{ secrets.COCREATE_ORGANIZATION_ID }}" >> $GITHUB_ENV
-          echo "key=${{ secrets.COCREATE_KEY }}" >> $GITHUB_ENV
-          echo "host=${{ secrets.COCREATE_HOST }}" >> $GITHUB_ENV
-      - name: CoCreate Upload
-        run: coc upload
-
+      new_release_version: "${{ steps.semantic.outputs.new_release_version }}"

package/CHANGELOG.md

@@ -1,3 +1,36 @@
+## [1.14.1](https://github.com/CoCreate-app/CoCreate-server-side-render/compare/v1.14.0...v1.14.1) (2026-07-17)
+
+
+### Bug Fixes
+
+* bump dependencies ([822bbc8](https://github.com/CoCreate-app/CoCreate-server-side-render/commit/822bbc8944b8782a69bff4e10ae0cb3fb2b02245))
+* update dependencies for improved compatibility and performance ([db6db94](https://github.com/CoCreate-app/CoCreate-server-side-render/commit/db6db94096338ab6a4daf58569549cdac4623d38))
+
+# [1.14.0](https://github.com/CoCreate-app/CoCreate-server-side-render/compare/v1.13.0...v1.14.0) (2026-07-17)
+
+
+### Features
+
+* update automated workflow and release configuration for improved semantic release handling ([30e01d7](https://github.com/CoCreate-app/CoCreate-server-side-render/commit/30e01d75c47cb36dc20f83a136d7eb296887d504))
+
+# [1.13.0](https://github.com/CoCreate-app/CoCreate-server-side-render/compare/v1.12.8...v1.13.0) (2026-07-14)
+
+
+### Bug Fixes
+
+* handle error states for fetched files in server-side rendering ([8c492c3](https://github.com/CoCreate-app/CoCreate-server-side-render/commit/8c492c39669082348bc920bb553479eb35ed35a1))
+* removed post install ([2ce8447](https://github.com/CoCreate-app/CoCreate-server-side-render/commit/2ce8447779ca84c2a887b7bfbac27a626aaaa044))
+* semantic version handling. Reorganize .gitignore for improved clarity and structure ([15bf544](https://github.com/CoCreate-app/CoCreate-server-side-render/commit/15bf5442decac9654746486d4d4cec8a1ad775b4))
+* update .gitignore to exclude package-lock.json and pnpm-lock.yaml ([7605dff](https://github.com/CoCreate-app/CoCreate-server-side-render/commit/7605dff02dd0b3071583e987d95ac723609515bc))
+* update module export to ES6 syntax in release.config.js ([a29e40f](https://github.com/CoCreate-app/CoCreate-server-side-render/commit/a29e40f1aa52b9113473ed27fbaffada015e03ff))
+* update package.json to use ESM and restructure server/client entry points ([e9b4c83](https://github.com/CoCreate-app/CoCreate-server-side-render/commit/e9b4c83720aa05dd9c45fc94fc070521357c32eb))
+
+
+### Features
+
+* optimize rendering logic and improve error handling in server-side rendering ([208aeba](https://github.com/CoCreate-app/CoCreate-server-side-render/commit/208aebac9efe650b7ef5c30713d5c6a4cc5b0aac))
+* update package.json and refactor index.js to use ES modules ([7ab7c9d](https://github.com/CoCreate-app/CoCreate-server-side-render/commit/7ab7c9d225505ef368c3434278d695eb7ac6f8d7))
+
 ## [1.12.8](https://github.com/CoCreate-app/CoCreate-server-side-render/compare/v1.12.7...v1.12.8) (2026-04-04)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cocreate/server-side-render",
-  "version": "1.12.8",
+  "version": "1.14.1",
   "description": "A simple server-side-render component in vanilla javascript. Easily configured using HTML5 data-attributes and/or JavaScript API.",
   "keywords": [
     "server-side-render",
@@ -16,10 +16,9 @@
     "access": "public"
   },
   "scripts": {
-    "start": "npx webpack --config webpack.config.js",
-    "build": "npx webpack --mode=production --config webpack.config.js",
-    "dev": "npx webpack --config webpack.config.js --watch",
-    "postinstall": "node -e \"const { execSync } = require('child_process'); try { execSync('coc --version', { stdio: 'ignore' }); } catch (error) { try { execSync('npm install -g @cocreate/cli', { stdio: 'inherit' }); console.log('Installed \"@cocreate/cli\" globally.'); } catch (error) { console.error('Failed to install \"@cocreate/cli\" globally:', error); } }\""
+    "start": "webpack --config webpack.config.js",
+    "build": "webpack --mode=production --config webpack.config.js",
+    "dev": "webpack --config webpack.config.js --watch"
   },
   "repository": {
     "type": "git",
@@ -35,9 +34,10 @@
     "type": "GitHub Sponsors ❤",
     "url": "https://github.com/sponsors/CoCreate-app"
   },
+  "type": "module",
   "main": "./src/index.js",
   "dependencies": {
-    "@cocreate/utils": "^1.39.0",
-    "node-html-parser": "^6.1.12"
+    "@cocreate/utils": "^1.44.0",
+    "node-html-parser": "^9.0.0"
   }
 }

package/release.config.js

@@ -1,4 +1,4 @@
-module.exports = {
+export default {
   dryRun: false,
   branches: ["master"],
   plugins: [
@@ -10,12 +10,20 @@ module.exports = {
         changelogFile: "CHANGELOG.md",
       },
     ],
-    "@semantic-release/npm",
-    "@semantic-release/github",
+    "@semantic-release/npm", 
     [
-      "@semantic-release/git",
+      "@semantic-release/github", 
       {
+        successComment: false,
+        failTitle: false,
+      },
+    ],
+    [
+      "@semantic-release/git", 
+      {
+        // Only stage and commit the changelog and package.json
         assets: ["CHANGELOG.md", "package.json"],
+        message: "chore(release): ${nextRelease.version} [skip ci]",
       },
     ],
   ],

package/src/index.js

@@ -1,285 +1,407 @@
-const { parse } = require("node-html-parser");
-const { checkValue, getRelativePath, ObjectId } = require("@cocreate/utils");
-const path = require("path");
-
-class CoCreateServerSideRender {
-	constructor(crud) {
-		this.crud = crud;
-	}
-
-	async HTML(file, organization, urlObject, langRegion, lang, theme) {
-		const self = this;
-		let ignoreElement = {
-			INPUT: true,
-			TEXTAREA: true,
-			SELECT: true,
-			LINK: true,
-			IFRAME: true,
-			"COCREATE-SELECT": true
-		};
-
-		let dep = [];
-		let dbCache = new Map();
-		let organization_id = file.organization_id;
-		const host = urlObject.hostname;
-
-		async function render(dom, lastKey) {
-			// Handle elements with [array][key][object]
-			for (let el of dom.querySelectorAll("[array][key][object]")) {
-				let meta = el.attributes;
-
-				if (ignoreElement[el.tagName]) continue;
-
-				if (el.closest(".template, [template], template, [render]"))
-					continue;
-
-				if (el.hasAttribute("render-query")) continue;
-
-				if (el.hasAttribute("component") || el.hasAttribute("plugin"))
-					continue;
-
-				if (el.hasAttribute("actions")) continue;
-
-				let _id = meta["object"],
-					array = meta["array"],
-					key = meta["key"];
-				let crudKey = _id + array + key;
-
-				if (!_id || !key || !array) continue;
-				if (!checkValue(_id) || !checkValue(key) || !checkValue(array))
-					continue;
-				if (dep.includes(crudKey))
-					throw new Error(
-						`infinite loop: ${lastKey} ${array} ${key} ${_id} has been already rendered`
-					);
-				else dep.push(crudKey);
-
-				let cacheKey = _id + array;
-				let data;
-				if (dbCache.has(cacheKey)) {
-					data = dbCache.get(cacheKey);
-				} else {
-					data = await self.crud.send({
-						method: "object.read",
-						host,
-						array,
-						object: { _id },
-						organization_id
-					});
-					if (data && data.object && data.object[0])
-						data = data.object[0];
-
-					dbCache.set(cacheKey, data);
-				}
-
-				if (!data || !data[key]) {
-					dep.pop();
-					continue;
-				}
-
-				let chunk = data[key];
-				if (!chunk) {
-					dep.pop();
-					continue;
-				}
-
-				chunk = await render(chunk);
-
-				el.setAttribute("rendered", "");
-				el.innerHTML = "";
-				el.appendChild(chunk);
-
-				dep.pop();
-			}
-
-			// ToDo: Fetch and render src, update relativePath. must have similar functionality to @cocreate/elements/fetch-src
-			// Handle elements with [src]
-			for (let el of dom.querySelectorAll(
-				"[src]:not(script, img, iframe, audio, video, source, track, input, embed, frame)"
-			)) {
-				let src = el.getAttribute("src");
-				if (!src) continue;
-
-				let path =
-					el.getAttribute("path") || getRelativePath(file.path);
-
-				if (path) {
-					src = src.replaceAll(/\$relativePath\/?/g, path);
-				}
-
-				let pathname = file.path
-				if (!pathname.endsWith("/")) {
-					pathname += "/";
-				}
-				// Construct actual pathname using src and the original URL
-				pathname = new URL(src, `http://localhost${pathname}`)
-					.pathname;
-
-				if (pathname.endsWith("/")) {
-					pathname += "index.html";
-				}
-				let $filter = {
-					query: {
-						pathname: pathname
-					}
-				}; // Use filter to structure query
-
-				let data = await self.crud.send({
-					method: "object.read",
-					host,
-					array: "files",
-					object: "",
-					$filter,
-					organization_id
-				});
-
-				if (
-					data &&
-					data.object &&
-					data.object[0] &&
-					data.object[0].src
-				) {
-					let chunk = data.object[0].src;
-
-					if (typeof chunk === "string" && chunk.startsWith("data:image/svg+xml;base64,")) {
-						chunk = Buffer.from(chunk.split(",")[1], "base64").toString("utf-8");
-					}
-
-					// Replace $relativePath in the fetched chunk
-					let path =
-						el.getAttribute("path") || getRelativePath(file.path);
-					if (path) {
-						chunk = chunk.replaceAll(/\$relativePath\/?/g, path);
-					}
-
-					// Replace ObjectId() with a new ObjectId
-					chunk = chunk.replaceAll("ObjectId()", () => {
-						// Generate a NEW ObjectId inside the function
-						return ObjectId().toString(); // Return its string representation
-					});
-
-					// Parse chunk into DOM before recursive rendering
-					let chunkDom = parse(chunk);
-					chunkDom = await render(chunkDom);
-
-					// If element requests outerHTML insertion, replace the element
-					// with the fetched chunk's content. Otherwise append children.
-					const valueType = el.getAttribute && el.getAttribute("value-type");
-					if (valueType === "outerHTML") {
-						// Replace the element with the parsed chunk's child nodes
-						// spread child nodes so we don't create an extra wrapper
-						if (chunkDom.childNodes && chunkDom.childNodes.length) {
-							el.replaceWith(...chunkDom.childNodes);
-						} else {
-							// If no child nodes, just remove the element
-							el.remove();
-						}
-					} else {
-						el.setAttribute("rendered", "");
-						el.innerHTML = "";
-						for (const child of chunkDom.childNodes) {
-							el.appendChild(child);
-						}
-					}
-				}
-			}
-
-			return dom;
-		}
-
-		let dom = parse(file.src);
-		dom = await render(dom, "root");
-		if (langRegion || lang) {
-			dom = await this.translate(dom, file, langRegion, lang);
-		}
-
-		// Inject preferred theme into the DOM so client gets server-rendered theme
-		if (theme) {
-			const htmlEl = dom.querySelector("html");
-			try {
-				if (htmlEl && htmlEl.setAttribute) htmlEl.setAttribute("data-bs-theme", theme);
-
-				const head = dom.querySelector("head");
-				if (head) {
-					// add or update color-scheme meta tag
-					let meta = head.querySelector('meta[name="color-scheme"]');
-					if (meta && meta.setAttribute) {
-						meta.setAttribute("content", theme);
-					} else {
-						const metaNode = parse(`<meta name="color-scheme" content="${theme}">`);
-						head.appendChild(metaNode);
-					}
-				}
-			} catch (e) {
-				// fail-safe: don't abort rendering if theme injection fails
-			}
-		}
-
-		if (organization.languages && organization.languages.length > 0) {
-			let langLinkTags = this.createLanguageLinkTags(
-				file,
-				organization,
-				urlObject
-			);
-			const head = dom.querySelector("head");
-			if (head && langLinkTags) {
-				const linksFragment = parse(langLinkTags);
-				for (const link of linksFragment.querySelectorAll("link")) {
-					head.appendChild(link);
-				}
-				// Remove the fragment node from the DOM if it exists
-				if (linksFragment.parentNode) {
-					linksFragment.remove();
-				}
-			}
-		}
-
-		dep = [];
-		dbCache.clear();
-		return dom.toString();
-	}
-
-	createLanguageLinkTags(file, organization, urlObject) {
-		let generatedLinksString = `<link rel="alternate" hreflang="x-default" href="https://${urlObject.hostname}${file.pathname}">\n`;
-
-		for (const language of organization.languages) {
-			let langPath = `/${language}${file.pathname}`;
-			const hrefUrl = `https://${urlObject.hostname}${langPath}`;
-			generatedLinksString += `<link rel="alternate" hreflang="${language}" href="${hrefUrl}">\n`;
-		}
-		return generatedLinksString;
-	}
-
-	async translate(dom, file, langRegion, lang) {
-		if (file.translations && (langRegion || lang)) {
-			for (let translation of file.translations) {
-				let elements = dom.querySelectorAll(translation.selector) || [];
-				for (let el of elements) {
-					if (!el) continue;
-					if (translation.innerHTML) {
-						let content =
-							translation.innerHTML[langRegion] ||
-							translation.innerHTML[lang];
-						if (content) {
-							el.innerHTML = content;
-						}
-					}
-					if (translation.attributes) {
-						for (let [key, languageObj] of Object.entries(
-							translation.attributes
-						)) {
-							let value =
-								languageObj[langRegion] || languageObj[lang];
-							if (value) {
-								el.setAttribute(key, value);
-							}
-						}
-					}
-				}
-			}
-		}
-		return dom;
-	}
+import { parse } from "node-html-parser";
+import { checkValue, ObjectId } from "@cocreate/utils";
+
+// Using a Set for O(1) lookups is cleaner and faster than an object map
+const IGNORE_ELEMENTS = new Set([
+   "FORM", "INPUT", "TEXTAREA", "SELECT", "LINK", "IFRAME", "COCREATE-SELECT"
+]);
+
+// Prevent these tags from triggering the generic [src] chunk-fetching logic
+const SKIP_SRC_ELEMENTS = new Set([
+    "SCRIPT", "IMG", "IFRAME", "AUDIO", "VIDEO", "SOURCE", "TRACK", "INPUT", "EMBED", "FRAME"
+]);
+
+// CSS Selector for identifying target elements
+const RENDER_SELECTOR = "[array], [src]:not(script, img, iframe, audio, video, source, track, input, embed, frame)";
+
+/**
+ * Main functional entry point for Server-Side Rendering.
+ * Completely stateless—all required dependencies are passed directly as arguments.
+ * @param {Object} options
+ * @param {Object} options.file - The template file object containing source markup
+ * @param {Object} options.organization - Organization configuration data
+ * @param {Object} options.urlObject - Request URL parsed object
+ * @param {string} options.langRegion - Target language region (e.g., 'en-US')
+ * @param {string} options.lang - Target language (e.g., 'en')
+ * @param {string} options.theme - Visual theme (e.g., 'dark')
+ * @param {Function} options.resolveFile - Injected custom file resolver callback
+ * @param {Object} options.crud - Crud database service instance
+ * @returns {Promise<string>} The fully rendered HTML string
+ */
+export async function HTML({
+    file,
+    organization,
+    urlObject,
+    langRegion,
+    lang,
+    theme,
+    resolveFile,
+    crud
+}) {
+    let dep = [];
+    let dbCache = new Map();
+    
+    const organization_id = file?.organization_id;
+    const host = urlObject?.hostname;
+
+    // Ensure file.path has a fallback to prevent runtime properties errors
+    const filePath = file?.path || file?.pathname || "/";
+
+    // Apply parsing directly on root file source without modifying any paths
+    let rootSrc = file?.src || "";
+    let dom = parse(rootSrc);
+
+    // Core Render Function (placed at the top for prominence)
+    async function render(currentDom, lastKey) {
+        // Find target elements and filter out nested targets to prevent redundant querying 
+        const elements = currentDom.querySelectorAll(RENDER_SELECTOR);
+
+        for (let el of elements) {
+            let isData = el.hasAttribute("array");
+            let isSrc = el.hasAttribute("src") && !SKIP_SRC_ELEMENTS.has(el.tagName.toUpperCase());
+
+            let chunkDom = null;
+
+            // 1. Process File Source (Takes priority over Data Source)
+            if (isSrc) {
+                let src = el.getAttribute("src");
+                // Explicitly check that src is a valid non-empty string (handling null in v9.x)
+                if (src && typeof src === "string") {
+                    let pathname = filePath;
+                    if (!pathname.endsWith("/")) pathname += "/";
+                    
+                    pathname = new URL(src, `http://localhost${pathname}`).pathname;
+                    if (pathname.endsWith("/")) pathname += "index.html";
+
+                    // CIRCULAR DEPENDENCY CHECK: Track active src resolution paths in loop prevention list
+                    let srcKey = `file:${pathname}`;
+                    if (dep.includes(srcKey)) {
+                        throw new Error(`Infinite loop detected: Parent context "${lastKey}" requested "${srcKey}", which is already in the active import chain.`);
+                    }
+                    dep.push(srcKey);
+
+                    let fetchedFile = null;
+
+                    // Use injected resolver callback if provided, otherwise fallback to CRUD query
+                    if (typeof resolveFile === "function") {
+                        fetchedFile = await resolveFile(pathname);
+                    } else if (crud) {
+                        let data = await crud.send({
+                            method: "object.read",
+                            host,
+                            array: "files",
+                            object: "",
+                            $filter: { query: { pathname } },
+                            organization_id
+                        });
+                        fetchedFile = data?.object?.[0] || null;
+                    }
+
+                    // Intelligent Status Code Handling
+                    let statusCode = fetchedFile?.status;
+                    if (!statusCode) {
+                        if (!fetchedFile || !fetchedFile.src) statusCode = 404;
+                        else if (fetchedFile.public === false || String(fetchedFile.public) === "false") statusCode = 403;
+                        else statusCode = 200;
+                    }
+
+                    if (statusCode >= 400) {
+                        el.setAttribute("error", statusCode.toString());
+                    } 
+
+                    // Render if status is successful OR if the element explicitly forces rendering errors via 'render-error'
+                    if (statusCode < 400 || el.hasAttribute("render-error")) {
+                        let chunkVal = fetchedFile?.src;
+
+                        if (chunkVal) {
+                            // Decode base64 SVG if necessary
+                            if (typeof chunkVal === "string" && chunkVal.startsWith("data:image/svg+xml;base64,")) {
+                                chunkVal = Buffer.from(chunkVal.split(",")[1], "base64").toString("utf-8");
+                            }
+
+                            // Normalize non-string values safely to strings before parsing (failsafe)
+                            let chunkStr = typeof chunkVal === 'string' ? chunkVal : String(chunkVal);
+                            chunkDom = parse(chunkStr);
+
+                            // Extract and merge any embedded <head> parameters before rendering nested items
+                            extractAndMergeHead(chunkDom, dom);
+                            
+                            // Passing dynamic srcKey instead of static "src-chunk" to preserve trace context
+                            chunkDom = await render(chunkDom, srcKey);
+                        }
+                    }
+                    dep.pop(); // Complete tracking cycle for this source resolution
+                }
+            }
+            // 2. Process Data Source (Only runs if element does not have a valid src being resolved)
+            else if (isData) {
+                let shouldProcessData = true;
+
+                // Exclude specific tags, templates, actions, and components from rendering
+                if (IGNORE_ELEMENTS.has(el.tagName.toUpperCase())) {
+                    shouldProcessData = false;
+                } else if (el.closest(".template, [template], template, [render]")) {
+                    shouldProcessData = false;
+                } else if (el.hasAttribute("render-query") || el.hasAttribute("component") || el.hasAttribute("plugin") || el.hasAttribute("actions")) {
+                    shouldProcessData = false;
+                }
+
+                if (shouldProcessData && crud) {
+                    let array = el.getAttribute("array");
+                    let key = el.getAttribute("key"); // Optional attribute
+                    let _id = el.getAttribute("object") || "";
+                    
+                    let $filter = {};
+                    let filterAttr = el.getAttribute("filter");
+                    if (filterAttr) {
+                        try {
+                            $filter = JSON.parse(filterAttr);
+                        } catch (e) {
+                            $filter = {};
+                        }
+                    }
+
+                    if (array && checkValue(array) && (!key || checkValue(key))) {
+                        let keyStr = key ? `-${key}` : '';
+                        let filterKeyStr = filterAttr ? `-${filterAttr}` : '';
+                        let crudKey = `${_id}${array}${keyStr}${filterKeyStr}`;
+                        
+                        if (dep.includes(crudKey)) {
+                            throw new Error(`Infinite loop detected: Parent context "${lastKey}" requested data key "${crudKey}", which has already been rendered.`);
+                        }
+                        dep.push(crudKey);
+
+                        let cacheKey = `${_id}${array}${filterKeyStr}`;
+                        let data;
+                        
+                        if (dbCache.has(cacheKey)) {
+                            data = dbCache.get(cacheKey);
+                        } else {
+                            data = await crud.send({
+                                method: "object.read",
+                                host,
+                                array,
+                                object: _id ? { _id } : "",
+                                $filter,
+                                organization_id
+                            });
+                            if (data?.object?.[0]) data = data.object[0];
+                            dbCache.set(cacheKey, data);
+                        }
+
+                        if (data) {
+                            // If a key is defined, fetch that key's value; otherwise, render the entire object/document
+                            let chunkVal = key ? data[key] : data;
+
+                            if (chunkVal !== undefined && chunkVal !== null) {
+                                // Normalize objects to JSON strings, and everything else safely to standard strings
+                                let chunkStr = typeof chunkVal === 'object' ? JSON.stringify(chunkVal) : String(chunkVal);
+                                chunkDom = parse(chunkStr);
+
+                                // Extract and merge any embedded <head> parameters before rendering nested items
+                                extractAndMergeHead(chunkDom, dom);
+
+                                // Recursively resolve all nested requirements in the chunk BEFORE inserting it
+                                chunkDom = await render(chunkDom, crudKey);
+                            }
+                        }
+                        dep.pop();
+                    }
+                }
+            }
+
+            // Apply DOM mutations only after everything in this sub-tree branch is completely resolved
+            if (chunkDom) {
+                if (el.getAttribute("value-type") === "outerHTML") {
+                    // Create a static array copy of childNodes to prevent mutation index shifts during replacement
+                    const childNodes = chunkDom.childNodes ? Array.from(chunkDom.childNodes) : [];
+                    if (childNodes.length) {
+                        el.replaceWith(...childNodes);
+                    } else {
+                        el.remove();
+                    }
+                } else {
+                    el.setAttribute("rendered", "");
+                    
+                    // Use modern set_content native helper for v9.0.0 (safer and cleaner than manually appending nodes)
+                    const contentToInject = chunkDom.childNodes && chunkDom.childNodes.length > 0 
+                        ? Array.from(chunkDom.childNodes) 
+                        : chunkDom;
+                    
+                    el.set_content(contentToInject);
+                }
+            }
+        }
+
+        return currentDom;
+    }
+
+    // Initialize recursion tracker with the primary file pathname to catch immediate self-reference imports
+    const rootNormalizedPath = filePath.endsWith("/") ? `${filePath}index.html` : filePath;
+    dep.push(`file:${rootNormalizedPath}`);
+
+    dom = await render(dom, "root");
+    
+    if (langRegion || lang) {
+        dom = translate(dom, file, langRegion, lang);
+    }
+
+    // Apply theme data-attributes/meta-tags if a head is available, or can be lazily resolved
+    if (theme) {
+        const htmlEl = dom.querySelector("html");
+        try {
+            if (htmlEl?.setAttribute) htmlEl.setAttribute("data-bs-theme", theme);
+
+            const currentHead = dom.querySelector("head");
+            if (currentHead) {
+                let meta = currentHead.querySelector('meta[name="color-scheme"]');
+                if (meta?.setAttribute) {
+                    meta.setAttribute("content", theme);
+                } else {
+                    const metaNode = parse(`<meta name="color-scheme" content="${theme}">`);
+                    currentHead.appendChild(metaNode);
+                }
+            }
+        } catch (e) {
+            // fail-safe
+        }
+    }
+
+    // Append localization link tags if head is present, or can be lazily resolved
+    if (organization?.languages?.length > 0) {
+        let langLinkTags = createLanguageLinkTags(file, organization, urlObject);
+        const currentHead = dom.querySelector("head");
+        if (currentHead && langLinkTags) {
+            const linksFragment = parse(langLinkTags);
+            for (const link of linksFragment.querySelectorAll("link")) {
+                currentHead.appendChild(link);
+            }
+        }
+    }
+
+    dep = [];
+    dbCache.clear();
+    
+    let finalHtml = dom.toString();
+
+    // Apply ObjectId generation globally across the fully rendered document
+    finalHtml = finalHtml.replaceAll("ObjectId()", () => ObjectId().toString());
+
+    return finalHtml;
 }
 
-module.exports = CoCreateServerSideRender;
+// ==========================================
+// Stateless Private Helper Functions
+// ==========================================
+
+function ensureMainHead(rootDom) {
+    let head = rootDom.querySelector("head");
+    if (!head) {
+        const htmlEl = rootDom.querySelector("html") || rootDom;
+        const headDom = parse("<head></head>");
+        head = headDom.querySelector("head");
+        if (htmlEl.childNodes && htmlEl.childNodes.length > 0) {
+            htmlEl.insertBefore(head, htmlEl.childNodes[0]);
+        } else {
+            htmlEl.appendChild(head);
+        }
+    }
+    return head;
+}
+
+function getMatchingSelector(newEl) {
+    const tagName = newEl.tagName.toUpperCase();
+    if (tagName === "TITLE") {
+        return "title";
+    }
+    if (tagName === "META") {
+        const name = newEl.getAttribute("name");
+        if (name) return `meta[name="${name}"]`;
+        const property = newEl.getAttribute("property");
+        if (property) return `meta[property="${property}"]`;
+    }
+    if (tagName === "SCRIPT") {
+        const type = newEl.getAttribute("type");
+        if (type === "application/ld+json") {
+            return 'script[type="application/ld+json"]';
+        }
+        const id = newEl.getAttribute("id");
+        if (id) return `script[id="${id}"]`;
+    }
+    if (tagName === "LINK") {
+        const rel = newEl.getAttribute("rel");
+        if (rel === "canonical") {
+            return 'link[rel="canonical"]';
+        }
+        const id = newEl.getAttribute("id");
+        if (id) return `link[id="${id}"]`;
+    }
+    return null;
+}
+
+function extractAndMergeHead(chunkDom, rootDom) {
+    const chunkHead = chunkDom.querySelector("head");
+    if (!chunkHead) return;
+
+    // Lazily ensure a main head exists on the root 'dom' since we found nested head assets to merge
+    const head = ensureMainHead(rootDom);
+
+    // Clone array of nodes to safely mutate during iteration
+    const children = [...chunkHead.childNodes];
+
+    for (const child of children) {
+        if (child.nodeType === 1) { // Element Node
+            const selector = getMatchingSelector(child);
+            let matched = false;
+            if (selector) {
+                const existing = head.querySelector(selector);
+                if (existing) {
+                    existing.replaceWith(child);
+                    matched = true;
+                }
+            }
+            if (!matched) {
+                head.appendChild(child);
+            }
+        } else {
+            // For text, script content, or comment nodes, append straight to main head
+            head.appendChild(child);
+        }
+    }
+
+    // Remove empty nested head container from the chunk
+    chunkHead.remove();
+}
+
+function createLanguageLinkTags(file, organization, urlObject) {
+    let generatedLinksString = `<link rel="alternate" hreflang="x-default" href="https://${urlObject.hostname}${file.pathname}">\n`;
+    for (const language of organization.languages) {
+        const hrefUrl = `https://${urlObject.hostname}/${language}${file.pathname}`;
+        generatedLinksString += `<link rel="alternate" hreflang="${language}" href="${hrefUrl}">\n`;
+    }
+    return generatedLinksString;
+}
+
+function translate(dom, file, langRegion, lang) {
+    if (!file?.translations || (!langRegion && !lang)) return dom;
+
+    for (let translation of file.translations) {
+        let elements = dom.querySelectorAll(translation.selector) || [];
+        for (let el of elements) {
+            if (!el) continue;
+            
+            if (translation.innerHTML) {
+                let content = translation.innerHTML[langRegion] || translation.innerHTML[lang];
+                if (content) el.innerHTML = content;
+            }
+            
+            if (translation.attributes) {
+                for (let [key, languageObj] of Object.entries(translation.attributes)) {
+                    let value = languageObj[langRegion] || languageObj[lang];
+                    if (value) el.setAttribute(key, value);
+                }
+            }
+        }
+    }
+    return dom;
+}