@cloudcannon/editable-regions 0.0.18 → 0.0.20-rc.1

package/integrations/eleventy/index.mjs

@@ -1,9 +1,22 @@
 import fs from "node:fs";
 import { builtinModules, createRequire } from "node:module";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import esbuild from "esbuild";
 import { createIncludeWithTag } from "../liquid/include-with-tag.mjs";
 
+/** This package's `integrations/eleventy/browser` directory. */
+const BROWSER_DIR = path.join(
+	path.dirname(fileURLToPath(import.meta.url)),
+	"browser",
+);
+
+/** Substituted for unbound `process` / `__dirname` / `__filename`. */
+const PROCESS_SHIM_PATH = path.join(BROWSER_DIR, "process-shim.mjs");
+
+/** Backs the generated module stubs; see `createBrowserStubPlugin`. */
+const STUB_MODE_PATH = path.join(BROWSER_DIR, "stub-mode.mjs");
+
 /**
  * @typedef {import("../../types/eleventy").LiquidOptions} LiquidOptions
  * @typedef {import("../../types/eleventy").PluginOptions} PluginOptions
@@ -95,6 +108,10 @@ export default function editableRegionsPlugin(eleventyConfig, pluginOptions) {
 			// The bundle imports the user's real Eleventy config (see
 			// `emitConfigMirror`), dragging in Node/build-time imports — stub them.
 			plugins: [createBrowserStubPlugin(liquidOptions.browserStub)],
+			// Node *globals* aren't imports, so the stub plugin can't reach them.
+			// esbuild defines `process.env.NODE_ENV` only; everything else is left
+			// unbound and throws at load.
+			inject: [PROCESS_SHIM_PATH],
 			outfile: options.output ?? `${dirs.output}/register-components.js`,
 		});
 	});
@@ -142,9 +159,13 @@ const ALWAYS_STUBBED = ["@cloudcannon/editable-regions/eleventy"];
 
 /**
  * esbuild plugin resolving Node built-ins and build-time-only packages to a
- * Proxy that survives `import` and property access but throws when called or
- * constructed — so the user's config bundles, and only a helper that actually
- * invokes a Node API at render time fails.
+ * Proxy that survives `import` and property access, so the user's config
+ * bundles for the browser. What happens when one is *called* depends on the
+ * phase — see `browser/stub-mode.mjs`.
+ *
+ * `process` is the exception: it resolves to the real shim, so an explicit
+ * `import … from "node:process"` reads the same values as the bare global
+ * that `inject` substitutes.
  *
  * @param {string[]} [extraStubs] - Extra specifiers to stub
  *   (`pluginOptions.liquid.browserStub`), e.g. native deps like `sharp`.
@@ -170,25 +191,39 @@ function createBrowserStubPlugin(extraStubs = []) {
 	return {
 		name: "editable-regions-browser-stub",
 		setup(build) {
-			build.onResolve({ filter: /.*/ }, (args) =>
-				shouldStub(args.path)
+			build.onResolve({ filter: /.*/ }, (args) => {
+				if (args.path === "process" || args.path === "node:process") {
+					return { path: args.path, namespace: "er-process" };
+				}
+				return shouldStub(args.path)
 					? { path: args.path, namespace: "er-stub" }
-					: null,
-			);
-			build.onLoad({ filter: /.*/, namespace: "er-stub" }, () => ({
+					: null;
+			});
+			// Re-exported as CommonJS rather than resolving straight to the shim:
+			// against an ES module, a named import esbuild can't match
+			// (`import { hrtime } from "node:process"`) is a hard build error,
+			// where CJS interop resolves it to `undefined` at runtime.
+			build.onLoad({ filter: /.*/, namespace: "er-process" }, () => ({
+				contents: `module.exports = require(${JSON.stringify(PROCESS_SHIM_PATH)}).process;`,
+				loader: "js",
+				resolveDir: BROWSER_DIR,
+			}));
+			build.onLoad({ filter: /.*/, namespace: "er-stub" }, (args) => ({
+				// CommonJS for the same reason as `er-process` above: a stub's
+				// export names aren't knowable, so named imports need CJS interop.
 				contents: `
+					const { onStubInvoked } = require(${JSON.stringify(STUB_MODE_PATH)});
+					const specifier = ${JSON.stringify(args.path)};
 					const handler = {
 						get: () => new Proxy(function () {}, handler),
-						apply: () => {
-							throw new Error("editable-regions: a Node/build-time API was called in the browser live-editing bundle. Provide a browser-friendly override via pluginOptions.liquid.<kind>.");
-						},
-						construct: () => {
-							throw new Error("editable-regions: a Node/build-time API was constructed in the browser live-editing bundle. Provide a browser-friendly override via pluginOptions.liquid.<kind>.");
-						},
+						apply: () => onStubInvoked(specifier, "called"),
+						construct: () => onStubInvoked(specifier, "constructed"),
 					};
 					module.exports = new Proxy(function () {}, handler);
 				`,
 				loader: "js",
+				// So the `require` above resolves out of the stub's namespace.
+				resolveDir: BROWSER_DIR,
 			}));
 		},
 	};
@@ -226,9 +261,12 @@ function resolveEleventyConfigPath(liquidOptions) {
  * skip; those are registered separately by `emitImportRegistrations` so the
  * override wins.
  *
+ * Split because the replay is awaited inside `initLiveEditing`, while an
+ * `import` can only live at module scope.
+ *
  * @param {string} configPath - Absolute path to the Eleventy config
  * @param {LiquidOptions | undefined} liquidOptions
- * @returns {string} JS source
+ * @returns {{imports: string, body: string}} JS source
  */
 function emitConfigMirror(configPath, liquidOptions) {
 	const skip = {
@@ -238,10 +276,10 @@ function emitConfigMirror(configPath, liquidOptions) {
 		tags: Object.keys(liquidOptions?.tags ?? {}),
 	};
 
-	return (
-		`\nimport userEleventyConfig from ${JSON.stringify(configPath)};\n` +
-		`collectAndRegisterEleventyHelpers(userEleventyConfig, ${JSON.stringify({ skip })});\n`
-	);
+	return {
+		imports: `\nimport userEleventyConfig from ${JSON.stringify(configPath)};\n`,
+		body: `await collectAndRegisterEleventyHelpers(userEleventyConfig, ${JSON.stringify({ skip })});\n`,
+	};
 }
 
 /**
@@ -339,9 +377,13 @@ async function generateLiveEditingSource(
 		// Auto-mirror the user's config helpers by importing and replaying the
 		// real config in the browser. See `emitConfigMirror`.
 		const configPath = resolveEleventyConfigPath(liquidOptions);
-		if (configPath) {
-			source += emitConfigMirror(configPath, liquidOptions);
-		} else {
+		const configMirror = configPath
+			? emitConfigMirror(configPath, liquidOptions)
+			: { imports: "", body: "" };
+
+		source += configMirror.imports;
+
+		if (!configPath) {
 			console.warn(
 				"[editable-regions] Could not locate an Eleventy config file to " +
 					"auto-mirror helpers from. Set `pluginOptions.liquid.configPath` " +
@@ -353,10 +395,18 @@ async function generateLiveEditingSource(
 
 		// Register browser-side overrides and pinned components. Override names
 		// are excluded from the mirror, so each is its name's sole registration.
-		source += emitImportRegistrations(liquidOptions);
+		const registrations = emitImportRegistrations(liquidOptions);
+		source += registrations.imports;
 
+		// One awaited sequence, so nothing registers ahead of the async replay and
+		// `window.cc_components` is published only once it's complete.
 		source += `
-      initComponentProxy();
+      async function initLiveEditing() {
+        ${configMirror.body}${registrations.body}
+        initComponentProxy();
+      }
+
+      initLiveEditing();
     `;
 	}
 	return source;
@@ -556,14 +606,15 @@ const IMPORT_REGISTER_FNS = {
  * Emits an `import` + register-call pair for every `{ name: modulePath }` entry
  * across the `IMPORT_REGISTER_FNS` maps, e.g.:
  *
- *   import filters_0 from "./path/to/file";
- *   registerFilter("name", filters_0);
+ *   import filters_0 from "./path/to/file";   // module scope
+ *   registerFilter("name", filters_0);        // inside `initLiveEditing`
  *
  * @param {LiquidOptions | undefined} liquidOptions
- * @returns {string} JS source
+ * @returns {{imports: string, body: string}} JS source
  */
 function emitImportRegistrations(liquidOptions) {
-	let out = "";
+	let imports = "";
+	let body = "";
 
 	for (const optionKey of /** @type {Array<keyof typeof IMPORT_REGISTER_FNS>} */ (
 		Object.keys(IMPORT_REGISTER_FNS)
@@ -574,9 +625,10 @@ function emitImportRegistrations(liquidOptions) {
 			liquidOptions?.[optionKey] ?? {},
 		).entries()) {
 			const id = `${optionKey}_${i}`;
-			out += `\nimport ${id} from "./${file}";\n${registerFn}(${JSON.stringify(name)}, ${id});\n`;
+			imports += `\nimport ${id} from "./${file}";\n`;
+			body += `${registerFn}(${JSON.stringify(name)}, ${id});\n`;
 		}
 	}
 
-	return out;
+	return { imports, body };
 }

package/integrations/hugo/browser/entry.js

@@ -0,0 +1,13 @@
+// Entry asset for the Hugo module's live-editing bundle. This file is a Go
+// template: editable-regions/resources.html renders it with the site's
+// snapshot via resources.ExecuteAsTemplate, then bundles the result with
+// js.Build. It is not valid JS until rendered — excluded from biome.
+//
+// The window.cc_hugo* assignments run before initHugoLiveEditing() in
+// program order, so the runtime reads a fully populated snapshot.
+window.cc_hugo = {{ .meta | jsonify }};
+window.cc_hugo_files = {{ .files | jsonify }};
+
+import { initHugoLiveEditing } from "./index.ts";
+
+initHugoLiveEditing();

package/integrations/hugo/browser/errors.ts

@@ -0,0 +1,41 @@
+/**
+ * Maps raw Hugo renderer errors to actionable messages. The message ends up
+ * on the core's component error card, so it should tell the user what to fix.
+ */
+
+export function enhanceHugoError(message: string, componentKey: string): Error {
+	let hint = "";
+
+	if (/partial .* not found/i.test(message)) {
+		hint =
+			" This partial isn't in the bundled template snapshot. Check that it " +
+			"lives under one of the directories in " +
+			"`params.editable_regions.template_dirs` (by default the partials, " +
+			"render hooks, and shortcodes of your configured layout dir) " +
+			"and rebuild the site.";
+	} else if (/execute of template failed/i.test(message)) {
+		hint =
+			" The partial errored while rendering in the editor. If it depends on " +
+			"build-only state (page context, resources, .Site.Pages), guard that " +
+			"code with `if hugo.IsServer` or move it out of the component.";
+	} else if (/logged \d+ errors/i.test(message)) {
+		hint =
+			" Hugo logged errors during the render — open the browser console " +
+			"for the underlying messages.";
+	}
+
+	return new Error(
+		`Failed to render Hugo component "${componentKey}": ${message}.${hint}`,
+	);
+}
+
+/** Error for a partial missing from the editor's template bundle; raised when
+ * the dispatch layout's `templates.Exists` check fails. */
+export function missingComponentError(componentKey: string): Error {
+	return new Error(
+		`No Hugo partial found for component "${componentKey}". This partial ` +
+			`isn't captured in the editor's template bundle. Make sure it's a ` +
+			`partial, shortcode, or render hook under your layout tree and ` +
+			`rebuild the site.`,
+	);
+}

package/integrations/hugo/browser/index.ts

@@ -0,0 +1,344 @@
+import "./wasm_exec.js";
+import {
+	apiLoadedPromise,
+	CloudCannon,
+} from "../../../helpers/cloudcannon.mjs";
+import { enhanceHugoError, missingComponentError } from "./errors.ts";
+import { group, groupEnd, log, setVerbose, warn } from "./logger.ts";
+
+/** A `(props) => HTMLElement` renderer installed on `window.cc_components`. */
+type HugoComponentRenderer = (
+	props?: Record<string, any>,
+) => Promise<HTMLElement>;
+
+/** The file being edited, captured once at boot; `""` when the open page has
+ * no associated file (the renderer then falls back to the home page). */
+let currentFilePath = "";
+
+/** @type {Promise<void> | null} */
+let enginePromise: Promise<void> | null = null;
+
+/**
+ * Entry point, called by the prebuilt runtime bundle. Installs the component
+ * proxy immediately and warms the WASM engine once the editor API appears —
+ * so loading the script on a production page never fetches the WASM.
+ */
+export function initHugoLiveEditing(): void {
+	const files = window.cc_hugo_files ?? {};
+
+	setVerbose(Boolean(window.cc_hugo?.verbose));
+	log(
+		"Hugo live editing initialized.",
+		Object.keys(files).length,
+		"templates in snapshot",
+	);
+
+	initComponentProxy();
+
+	apiLoadedPromise.then(() => {
+		ensureEngine().catch((err) => {
+			warn("Failed to start the Hugo renderer:", err);
+		});
+	});
+}
+
+/** Boots the WASM renderer once and builds the editor site from the snapshot. */
+export function ensureEngine(): Promise<void> {
+	if (!enginePromise) {
+		enginePromise = startEngine().catch((err) => {
+			// Allow a retry on transient failures (e.g. a dropped WASM fetch).
+			enginePromise = null;
+			throw err;
+		});
+	}
+	return enginePromise;
+}
+
+async function startEngine(): Promise<void> {
+	const wasmUrl =
+		window.cc_hugo?.wasmUrl ?? "/_cloudcannon/hugo_renderer.wasm.gz";
+
+	group("Starting Hugo renderer");
+	log("Fetching WASM from", wasmUrl);
+
+	const response = await fetch(wasmUrl);
+	if (!response.ok || !response.body) {
+		groupEnd();
+		throw new Error(
+			`Failed to fetch Hugo WASM from ${wasmUrl}: HTTP ${response.status}`,
+		);
+	}
+
+	let wasmBuffer: ArrayBuffer;
+	if (wasmUrl.endsWith(".gz")) {
+		const decompressed = response.body.pipeThrough(
+			new DecompressionStream("gzip"),
+		);
+		wasmBuffer = await new Response(decompressed).arrayBuffer();
+	} else {
+		wasmBuffer = await response.arrayBuffer();
+	}
+
+	const go = new (globalThis as any).Go();
+	const { instance } = await WebAssembly.instantiate(
+		wasmBuffer,
+		go.importObject,
+	);
+	go.run(instance);
+
+	// The Go side registers its globals synchronously at startup.
+	while (
+		typeof (globalThis as { renderHugoPartials?: unknown })
+			.renderHugoPartials !== "function"
+	) {
+		await new Promise((resolve) => setTimeout(resolve, 10));
+	}
+
+	const files = {
+		...(window.cc_hugo_files ?? {}),
+		"cc-env": window.cc_hugo?.env ?? "production",
+	};
+	writeHugoFiles(JSON.stringify(files));
+
+	await loadAPIData();
+
+	const initError = initHugoEditorSite();
+
+	if (initError?.error) {
+		groupEnd();
+		throw new Error(`Hugo editor site failed to build: ${initError.error}`);
+	}
+
+	log("Hugo renderer ready");
+	groupEnd();
+}
+
+async function loadAPIData(): Promise<void> {
+	const files: Record<string, string> = {};
+	try {
+		currentFilePath = CloudCannon.currentFile().path;
+	} catch {
+		currentFilePath = "";
+	}
+	const currentPath = currentFilePath;
+
+	const collections = await CloudCannon.collections();
+	for (const collection of collections) {
+		collection.addEventListener("change", async (event) => {
+			const path = event.detail.sourcePath;
+			const frontMatter = await CloudCannon.file(path).data.get();
+			if (!frontMatter || typeof frontMatter !== "object") {
+				return;
+			}
+
+			writeHugoFiles(
+				JSON.stringify({
+					[path]: `---\n${JSON.stringify(frontMatter)}\n---\n`,
+				}),
+			);
+		});
+		collection.addEventListener("delete", (event) => {
+			if (currentPath !== event.detail.sourcePath) {
+				removeHugoFiles(JSON.stringify([event.detail.sourcePath]));
+			}
+		});
+
+		const items = await collection.items();
+		for (const file of items) {
+			const frontMatter = await file.data.get();
+			if (!frontMatter || typeof frontMatter !== "object") continue;
+			files[file.path] = `---\n${JSON.stringify(frontMatter)}\n---\n`;
+		}
+	}
+
+	const datasets = await CloudCannon.datasets();
+	for (const dataset of datasets) {
+		dataset.addEventListener("change", async (event) => {
+			const data = await CloudCannon.file(event.detail.sourcePath).data.get();
+			if (data === undefined || data === null) return;
+			writeHugoFiles(
+				JSON.stringify({
+					[datasetPath(event.detail.sourcePath)]: `${JSON.stringify(data)}\n`,
+				}),
+			);
+		});
+		dataset.addEventListener("delete", (event) => {
+			removeHugoFiles(JSON.stringify([datasetPath(event.detail.sourcePath)]));
+		});
+
+		const result = await dataset.items();
+		for (const file of Array.isArray(result) ? result : [result]) {
+			const data = await file.data.get();
+			if (data === undefined || data === null) continue;
+			files[datasetPath(file.path)] = `${JSON.stringify(data)}\n`;
+		}
+	}
+
+	if (Object.keys(files).length > 0) {
+		log(
+			`Loading editor content: ${Object.keys(files).length} files (editing ${currentPath})`,
+		);
+		writeHugoFiles(JSON.stringify(files));
+	}
+}
+
+/**
+ * Maps a dataset's source path to its mirrored data-dir path. `.yaml`/`.yml`/`.json`
+ * keep their extension (Hugo natively decodes all three); anything else is
+ * rewritten to `.json` so a decoder Hugo understands handles it.
+ */
+function datasetPath(apiPath: string): string {
+	if (/\.(ya?ml|json)$/i.test(apiPath)) return apiPath;
+	return `${apiPath.replace(/\.[^./]*$/, "")}.json`;
+}
+
+/**
+ * Queues a partial render, resolving with the rendered element once the batch
+ * window closes; all callers get batching transparently.
+ */
+interface QueuedRender {
+	id: string;
+	partial: string;
+	props: Record<string, any>;
+	resolve: (el: HTMLElement) => void;
+	reject: (err: unknown) => void;
+}
+
+const BATCH_WINDOW_MS = 10;
+
+let batch: QueuedRender[] = [];
+let batchTimer: ReturnType<typeof setTimeout> | null = null;
+let nextRenderId = 0;
+
+/**
+ * Queues a partial render, resolving with the rendered element once the batch
+ * window closes; all callers get batching transparently.
+ */
+export async function renderHugoPartial(
+	partial: string,
+	props: Record<string, any> = {},
+): Promise<HTMLElement> {
+	await ensureEngine();
+
+	return new Promise<HTMLElement>((resolve, reject) => {
+		const id = `cc-render-${nextRenderId++}`;
+		log("Queueing Hugo component:", partial, "Props:", props);
+		batch.push({ id, partial, props, resolve, reject });
+		if (batchTimer === null) {
+			batchTimer = setTimeout(flushBatch, BATCH_WINDOW_MS);
+		}
+	});
+}
+
+/** Flushes the batch: one renderer call, then demux the keyed output. */
+function flushBatch(): void {
+	batchTimer = null;
+	const queued = batch;
+	batch = [];
+	if (queued.length === 0) return;
+
+	group(`Rendering ${queued.length} Hugo component(s)`);
+	try {
+		const result = renderHugoPartials(
+			JSON.stringify({
+				target: currentFilePath,
+				requests: queued.map(({ id, partial, props }) => ({
+					id,
+					partial,
+					props,
+				})),
+			}),
+		);
+		demuxBatch(queued, result);
+	} catch (err) {
+		for (const { partial, reject } of queued) {
+			reject(enhanceHugoError(String(err), partial));
+		}
+	}
+	groupEnd();
+}
+
+/**
+ * Resolves each request's keyed element from the combined output; errors and
+ * missing partials fail only the calls they apply to, the rest still resolves.
+ */
+function demuxBatch(
+	queued: QueuedRender[],
+	result: { html?: string; error?: string } | null,
+): void {
+	if (result?.error || typeof result?.html !== "string") {
+		log("Render error:", result?.error);
+		for (const { partial, reject } of queued) {
+			reject(enhanceHugoError(result?.error ?? "no output", partial));
+		}
+		return;
+	}
+
+	const holder = document.createElement("div");
+	holder.innerHTML = result.html;
+	for (const render of queued) {
+		const keyed = holder.querySelector<HTMLElement>(
+			`[data-cc-render="${render.id}"]`,
+		);
+		if (!keyed) {
+			render.reject(
+				new Error(
+					`Hugo render produced no output for component "${render.partial}"`,
+				),
+			);
+			continue;
+		}
+
+		const missing = keyed.querySelector("cc-missing-partial");
+		if (missing) {
+			render.reject(
+				missingComponentError(
+					missing.getAttribute("data-name") || render.partial,
+				),
+			);
+			continue;
+		}
+
+		const failed = keyed.querySelector("cc-failed-partial");
+		if (failed) {
+			render.reject(
+				enhanceHugoError(
+					failed.getAttribute("data-message") || "unknown error",
+					failed.getAttribute("data-name") || render.partial,
+				),
+			);
+			continue;
+		}
+
+		keyed.removeAttribute("data-cc-render");
+		log("Rendered HTML preview:", keyed.innerHTML.substring(0, 200));
+		render.resolve(keyed);
+	}
+}
+
+/** Builds the `(props) => HTMLElement` renderer the shared core calls. */
+function createComponentRenderer(key: string): HugoComponentRenderer {
+	return async (props: Record<string, any> = {}) => {
+		// Render only once the engine is ready; the flush then sends the
+		// boot-captured currentFilePath as the batch's shared target.
+		await ensureEngine();
+		return renderHugoPartial(key, props);
+	};
+}
+
+export function initComponentProxy(): void {
+	const win = window;
+	const target = win.cc_components ?? {};
+
+	win.cc_components = new Proxy(target, {
+		get(registered, key, receiver) {
+			if (Reflect.has(registered, key)) {
+				return Reflect.get(registered, key, receiver);
+			}
+			if (typeof key === "string") {
+				return createComponentRenderer(key);
+			}
+			return undefined;
+		},
+	});
+}

package/integrations/hugo/browser/logger.ts

@@ -0,0 +1,42 @@
+// Module-local logger; logging is gated on verbose mode, except
+// `warn`/`warnOnce`.
+
+let verboseEnabled = false;
+
+export function setVerbose(enabled: boolean): void {
+	verboseEnabled = enabled;
+	if (enabled) {
+		console.log("Live editing verbose logging enabled");
+	}
+}
+
+export function log(...args: any[]): void {
+	if (verboseEnabled) {
+		console.log(...args);
+	}
+}
+
+export function warn(...args: any[]): void {
+	console.warn(...args);
+}
+
+const warnedKeys = new Set<string>();
+
+/** Warns once per key for the lifetime of the page. */
+export function warnOnce(key: string, ...args: any[]): void {
+	if (warnedKeys.has(key)) return;
+	warnedKeys.add(key);
+	warn(...args);
+}
+
+export function group(label: string): void {
+	if (verboseEnabled) {
+		console.group(label);
+	}
+}
+
+export function groupEnd(): void {
+	if (verboseEnabled) {
+		console.groupEnd();
+	}
+}