@cloudcannon/editable-regions 0.0.20-rc.2 → 0.0.20

package/components/ui/editable-region-error-card.ts

@@ -64,6 +64,15 @@ export default class EditableRegionErrorCard extends HTMLElement {
 
 				body.appendChild(stack);
 			}
+
+			if ("hint" in error && typeof error.hint === "string") {
+				const hint = error.hint;
+				const hintElement = document.createElement("p");
+				hintElement.className = "hint";
+				hintElement.innerHTML = hint;
+
+				body.appendChild(hintElement);
+			}
 		}
 
 		if (this.hasAttribute("hint")) {

package/helpers/cloudcannon.mjs

@@ -14,24 +14,26 @@
  * }} ExtendedWindow
  */
 
-/** @type {ExtendedWindow} */
-const extendedWindow = /** @type {any} */ (window);
+/** @type {ExtendedWindow | undefined} */
+const extendedWindow = /** @type {any} */ (
+	typeof window === "undefined" ? undefined : window
+);
 
-/** @type {CloudCannonVisualEditorAPIV1} */
+/** @type {CloudCannonVisualEditorAPIV1 | undefined} */
 let _cloudcannon;
 
 /** @type {Promise<void>} */
 export const apiLoadedPromise = new Promise((resolve) => {
-	if (extendedWindow.CloudCannonAPI) {
+	if (extendedWindow?.CloudCannonAPI) {
 		_cloudcannon = /** @type {any} */ (
 			extendedWindow.CloudCannonAPI.useVersion("v1", true)
 		);
 		resolve();
-	} else {
+	} else if (typeof document !== "undefined") {
 		document.addEventListener(
 			"cloudcannon:load",
 			() => {
-				if (extendedWindow.CloudCannonAPI) {
+				if (extendedWindow?.CloudCannonAPI) {
 					_cloudcannon = /** @type {any} */ (
 						extendedWindow.CloudCannonAPI.useVersion("v1", true)
 					);
@@ -48,6 +50,9 @@ export const apiLoadedPromise = new Promise((resolve) => {
  * @param {ComponentRenderer} renderer
  */
 export const addEditableComponentRenderer = (key, renderer) => {
+	if (!extendedWindow) {
+		return;
+	}
 	extendedWindow.cc_components = extendedWindow.cc_components || {};
 	extendedWindow.cc_components[key] = renderer;
 };
@@ -57,15 +62,18 @@ export const addEditableComponentRenderer = (key, renderer) => {
  * @param {ComponentRenderer} renderer
  */
 export const addEditableSnippetRenderer = (key, renderer) => {
+	if (!extendedWindow) {
+		return;
+	}
 	extendedWindow.cc_snippets = extendedWindow.cc_snippets || {};
 	extendedWindow.cc_snippets[key] = renderer;
 };
 
 export const getEditableComponentRenderers = () =>
-	extendedWindow.cc_components ?? {};
+	extendedWindow?.cc_components ?? {};
 
 export const getEditableSnippetRenderers = () =>
-	extendedWindow.cc_snippets ?? {};
+	extendedWindow?.cc_snippets ?? {};
 
 /**
  * Resolves CloudCannon API objects (collections, files, datasets) to plain data.
@@ -91,13 +99,16 @@ export const realizeAPIValue = async (value) => {
 };
 
 export const addCustomEditableRegion = (key, region) => {
+	if (!extendedWindow || typeof document === "undefined") {
+		return;
+	}
 	extendedWindow.editableRegionMap ??= {};
 	extendedWindow.editableRegionMap[key] = region;
 	extendedWindow.hydrateDataEditableRegions(document.body);
 };
 
 export const getCustomEditableRegions = () => {
-	return extendedWindow.editableRegionMap ?? {};
+	return extendedWindow?.editableRegionMap ?? {};
 };
 
 export { _cloudcannon as CloudCannon };

package/helpers/hydrate-editable-regions.ts

@@ -10,6 +10,8 @@ import {
 import { hasEditable } from "../nodes/editable.js";
 import { isEditableWebcomponent } from "./checks";
 
+const DYNAMIC_EDITABLE_TYPE = "_dynamic";
+
 const baseEditableMap: Record<string, typeof Editable | undefined> = {
 	array: EditableArray,
 	"array-item": EditableArrayItem,
@@ -20,12 +22,23 @@ const baseEditableMap: Record<string, typeof Editable | undefined> = {
 };
 
 export const dehydrateDataEditableRegions = (root: Element) => {
-	if (root instanceof HTMLElement && hasEditable(root)) {
+	if (
+		root instanceof HTMLElement &&
+		hasEditable(root) &&
+		root.dataset.editable !== DYNAMIC_EDITABLE_TYPE
+	) {
 		root.editable.disconnect();
 	}
 
 	root.querySelectorAll("[data-editable]").forEach((element) => {
-		if (element instanceof HTMLElement && hasEditable(element)) {
+		if (
+			!(element instanceof HTMLElement) ||
+			element.dataset.editable === DYNAMIC_EDITABLE_TYPE
+		) {
+			return;
+		}
+
+		if (hasEditable(element)) {
 			element.editable.disconnect();
 		}
 	});
@@ -39,6 +52,7 @@ export const hydrateDataEditableRegions = (root: Element) => {
 	if (
 		root instanceof HTMLElement &&
 		root.dataset.editable &&
+		root.dataset.editable !== DYNAMIC_EDITABLE_TYPE &&
 		!isEditableWebcomponent(root)
 	) {
 		if ("editable" in root && root.editable instanceof Editable) {
@@ -64,6 +78,10 @@ export const hydrateDataEditableRegions = (root: Element) => {
 			return;
 		}
 
+		if (element.dataset.editable === DYNAMIC_EDITABLE_TYPE) {
+			return;
+		}
+
 		const Editable = editableMap[element.dataset.editable];
 		if (!Editable) {
 			const error = document.createElement("editable-region-error-card");
@@ -95,4 +113,19 @@ export const hydrateDataEditableRegions = (root: Element) => {
 	});
 };
 
-(window as any).hydrateDataEditableRegions = hydrateDataEditableRegions;
+const extendedWindow = /** @type {any} */ (window);
+
+Object.assign(extendedWindow, {
+	editableRegions: {
+		Editable,
+		EditableArray,
+		EditableArrayItem,
+		EditableComponent,
+		EditableImage,
+		EditableSource,
+		EditableText,
+	},
+	hydrateDataEditableRegions,
+});
+
+document.dispatchEvent(new CustomEvent("editable-regions:load"));

package/integrations/hugo/browser/errors.ts

@@ -3,30 +3,101 @@
  * on the core's component error card, so it should tell the user what to fix.
  */
 
-export function enhanceHugoError(message: string, componentKey: string): Error {
+const TEMPLATE_FRAME_RE =
+	/^template: (.+?): executing ".*?" at .*?: error calling (.+?): /;
+const FAILED_SEPARATOR = ": execute of template failed: ";
+
+export interface ParsedHugoError {
+	/** Template refs (file:line:column), outermost call first. */
+	frames: string[];
+	/** The template function whose call failed in the innermost frame. */
+	call?: string;
+	/** The underlying error, with the template-call chain stripped. */
+	message: string;
+}
+
+export function parseHugoTemplateError(raw: string): ParsedHugoError {
+	const frames: string[] = [];
+	let call: string | undefined;
+	let rest = raw.trim();
+	for (;;) {
+		const match = rest.match(TEMPLATE_FRAME_RE);
+		if (!match) break;
+		frames.push(match[1]);
+		call = match[2];
+		rest = rest.slice(match[0].length);
+		const quotedSeparator = rest.match(
+			/^"[^"]*": execute of template failed: /,
+		);
+		if (quotedSeparator) {
+			rest = rest.slice(quotedSeparator[0].length);
+		} else {
+			const separator = rest.indexOf(FAILED_SEPARATOR);
+			const after =
+				separator === -1 ? "" : rest.slice(separator + FAILED_SEPARATOR.length);
+			if (after.startsWith("template: ")) {
+				rest = after;
+			}
+		}
+	}
+	return { frames, call, message: rest };
+}
+
+/** An error enhanced with an optional editor-context hint. */
+export type HugoError = Error & { hint?: string };
+
+export function enhanceHugoError(
+	message: string,
+	componentKey: string,
+): HugoError {
+	const parsed = parseHugoTemplateError(message);
+
 	let hint = "";
 
 	if (/partial .* not found/i.test(message)) {
 		hint =
-			" This partial isn't in the bundled template snapshot. Check that it " +
+			"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)) {
+	} else if (parsed.frames.length > 0) {
 		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.";
+			"The partial errored while rendering in the editor. If the code " +
+			"should only run in the site build, guard it with " +
+			"`{{ if not site.Params.env_client }}`, " +
+			"or supply an editor-safe version via " +
+			"`params.editable_regions.templates_overrides`.";
 	} else if (/logged \d+ errors/i.test(message)) {
 		hint =
-			" Hugo logged errors during the render — open the browser console " +
+			"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}`,
-	);
+	const primary =
+		parsed.frames.length > 0 && parsed.call
+			? `${parsed.call}: ${parsed.message}`
+			: parsed.message;
+	const sentence = /[.!?]$/.test(primary) ? primary : `${primary}.`;
+
+	const error = new Error(
+		`Failed to render Hugo component "${componentKey}": ${sentence}`,
+	) as HugoError;
+
+	if (hint) {
+		error.hint = hint;
+	}
+
+	if (parsed.frames.length > 0) {
+		error.stack = parsed.frames
+			.slice()
+			.reverse()
+			.slice(0, 10)
+			.map((ref) => `    at ${ref}`)
+			.join("\n");
+	}
+
+	return error;
 }
 
 /** Error for a partial missing from the editor's template bundle; raised when

package/integrations/hugo/browser/hugo-renderer.ts

@@ -0,0 +1,282 @@
+import { enhanceHugoError, missingComponentError } from "./errors.ts";
+import { HugoWasm } from "./hugo-wasm.ts";
+import { group, groupEnd, log, warn } from "./logger.ts";
+import type { WorkerRequest, WorkerResponse } from "./worker-protocol.ts";
+
+export interface EngineTransport {
+	boot(args: {
+		wasmUrl: string;
+		env: string;
+		files: Record<string, string>;
+	}): Promise<void>;
+	writeFiles(json: string): Promise<void>;
+	removeFiles(json: string): Promise<void>;
+	init(): Promise<string | undefined>;
+	render(payload: string): Promise<{ html?: string; error?: string }>;
+}
+
+class WorkerClient implements EngineTransport {
+	private pending = new Map<string, (response: WorkerResponse) => void>();
+	private nextId = 0;
+
+	constructor(private worker: Worker) {
+		worker.onmessage = (event: MessageEvent<WorkerResponse>) => {
+			const response = event.data;
+			this.pending.get(response.id)?.(response);
+			this.pending.delete(response.id);
+		};
+	}
+
+	private send(request: WorkerRequest): Promise<WorkerResponse> {
+		return new Promise((resolve) => {
+			this.pending.set(request.id, resolve);
+			this.worker.postMessage(request);
+		});
+	}
+
+	async boot({
+		wasmUrl,
+		env,
+		files,
+	}: {
+		wasmUrl: string;
+		env: string;
+		files: Record<string, string>;
+	}): Promise<void> {
+		const response = await this.send({
+			id: `cc-worker-${this.nextId++}`,
+			kind: "boot",
+			wasmUrl,
+			env,
+			files,
+		});
+		if (response.error) {
+			throw new Error(response.error);
+		}
+	}
+
+	async writeFiles(json: string): Promise<void> {
+		await this.send({
+			id: `cc-worker-${this.nextId++}`,
+			kind: "writeFiles",
+			json,
+		});
+	}
+
+	async removeFiles(json: string): Promise<void> {
+		await this.send({
+			id: `cc-worker-${this.nextId++}`,
+			kind: "removeFiles",
+			json,
+		});
+	}
+
+	async init(): Promise<string | undefined> {
+		const response = await this.send({
+			id: `cc-worker-${this.nextId++}`,
+			kind: "init",
+		});
+		return response.error;
+	}
+
+	async render(payload: string): Promise<{ html?: string; error?: string }> {
+		const response = await this.send({
+			id: `cc-worker-${this.nextId++}`,
+			kind: "render",
+			payload,
+		});
+		return { html: response.html, error: response.error };
+	}
+}
+
+interface QueuedRender {
+	id: string;
+	partial: string;
+	props: Record<string, any>;
+	resolve: (el: HTMLElement) => void;
+	reject: (err: unknown) => void;
+}
+
+const BATCH_WINDOW_MS = 10;
+
+export interface HugoRendererOptions {
+	wasmUrl: string;
+	env: string;
+	workerUrl?: string;
+	getTarget: () => string;
+	getFiles: () => Record<string, string>;
+	onBooted?: () => Promise<void>;
+}
+
+/**
+ * Main-thread facade over the Hugo engine: owns batching, the render-id demux
+ * into real elements, and transport selection. Runs the engine in a worker
+ * when one is provided and constructible, falling back to an in-page
+ * HugoWasm; the interface returns HTMLElements either way.
+ */
+export class HugoRenderer {
+	private enginePromise: Promise<void> | null = null;
+	private transportPromise: Promise<EngineTransport> | null = null;
+	private batch: QueuedRender[] = [];
+	private batchTimer: ReturnType<typeof setTimeout> | null = null;
+	private nextRenderId = 0;
+
+	constructor(private options: HugoRendererOptions) {}
+
+	async ready(): Promise<void> {
+		this.enginePromise ??= this.start().catch((err) => {
+			this.enginePromise = null;
+			this.transportPromise = null;
+			throw err;
+		});
+		await this.enginePromise;
+	}
+
+	async writeFiles(json: string): Promise<void> {
+		await (await this.transport()).writeFiles(json);
+	}
+
+	async removeFiles(json: string): Promise<void> {
+		await (await this.transport()).removeFiles(json);
+	}
+
+	async renderPartial(
+		partial: string,
+		props: Record<string, any> = {},
+	): Promise<HTMLElement> {
+		await this.ready();
+		return new Promise<HTMLElement>((resolve, reject) => {
+			const id = `cc-render-${this.nextRenderId++}`;
+			log("Queueing Hugo component:", partial, "Props:", props);
+			this.batch.push({ id, partial, props, resolve, reject });
+			if (this.batchTimer === null) {
+				this.batchTimer = setTimeout(() => this.flushBatch(), BATCH_WINDOW_MS);
+			}
+		});
+	}
+
+	private transport(): Promise<EngineTransport> {
+		this.transportPromise ??= Promise.resolve(this.createEngine());
+		return this.transportPromise;
+	}
+
+	private createEngine(): EngineTransport {
+		if (this.options.workerUrl && typeof Worker === "function") {
+			try {
+				log("Starting Hugo renderer in a worker");
+				return new WorkerClient(new Worker(this.options.workerUrl));
+			} catch {
+				warn("Hugo worker unavailable, rendering on the main thread");
+			}
+		}
+		return new HugoWasm();
+	}
+
+	private async start(): Promise<void> {
+		const engine = await this.transport();
+
+		group("Starting Hugo renderer");
+		await engine.boot({
+			wasmUrl: this.options.wasmUrl,
+			env: this.options.env,
+			files: this.options.getFiles(),
+		});
+		await this.options.onBooted?.();
+
+		const initError = await engine.init();
+		if (initError) {
+			groupEnd();
+			throw new Error(`Hugo editor site failed to build: ${initError}`);
+		}
+
+		log("Hugo renderer ready");
+		groupEnd();
+	}
+
+	private flushBatch(): void {
+		this.batchTimer = null;
+		const queued = this.batch;
+		this.batch = [];
+		if (queued.length === 0) return;
+
+		group(`Rendering ${queued.length} Hugo component(s)`);
+		this.runBatch(queued);
+	}
+
+	private async runBatch(queued: QueuedRender[]): Promise<void> {
+		try {
+			const engine = await this.ready().then(() => this.transport());
+			const result = await engine.render(
+				JSON.stringify({
+					target: this.options.getTarget(),
+					requests: queued.map(({ id, partial, props }) => ({
+						id,
+						partial,
+						props,
+					})),
+				}),
+			);
+			this.demuxBatch(queued, result);
+		} catch (err) {
+			for (const { partial, reject } of queued) {
+				reject(enhanceHugoError(String(err), partial));
+			}
+		} finally {
+			groupEnd();
+		}
+	}
+
+	private 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);
+		}
+	}
+}

package/integrations/hugo/browser/hugo-wasm.ts

@@ -0,0 +1,116 @@
+import "./wasm_exec.js";
+
+export interface HugoWasmBootArgs {
+	wasmUrl: string;
+	env: string;
+	files: Record<string, string>;
+}
+
+interface PendingOp {
+	run: () => Promise<unknown>;
+	resolve: (value: unknown) => void;
+	reject: (err: unknown) => void;
+}
+
+export class HugoWasm {
+	private pending: PendingOp[] = [];
+	private draining = false;
+
+	async boot(args: HugoWasmBootArgs): Promise<void> {
+		await this.enqueue(() => this.runBoot(args));
+	}
+
+	writeFiles(json: string): Promise<void> {
+		return this.enqueue(async () => {
+			writeHugoFiles(json);
+		});
+	}
+
+	removeFiles(json: string): Promise<void> {
+		return this.enqueue(async () => {
+			removeHugoFiles(json);
+		});
+	}
+
+	async init(): Promise<string | undefined> {
+		return this.enqueue(async () => initHugoEditorSite()?.error);
+	}
+
+	render(payload: string): Promise<{ html?: string; error?: string }> {
+		return this.enqueue(
+			() =>
+				new Promise((resolve) => {
+					renderHugoPartials(payload, resolve);
+				}),
+		);
+	}
+
+	private enqueue<T>(run: () => Promise<T>): Promise<T> {
+		return new Promise<T>((resolve, reject) => {
+			this.pending.push({
+				run,
+				resolve: resolve as (value: unknown) => void,
+				reject,
+			});
+			this.pump();
+		});
+	}
+
+	private pump(): void {
+		if (this.draining) return;
+		this.draining = true;
+		this.drain();
+	}
+
+	private async drain(): Promise<void> {
+		while (this.pending.length > 0) {
+			const op = this.pending.shift();
+			if (!op) break;
+			try {
+				op.resolve(await op.run());
+			} catch (err) {
+				op.reject(err);
+			}
+		}
+		this.draining = false;
+	}
+
+	private async runBoot({
+		wasmUrl,
+		env,
+		files,
+	}: HugoWasmBootArgs): Promise<void> {
+		const response = await fetch(wasmUrl);
+		if (!response.ok || !response.body) {
+			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);
+
+		while (
+			typeof (globalThis as { renderHugoPartials?: unknown })
+				.renderHugoPartials !== "function"
+		) {
+			await new Promise((resolve) => setTimeout(resolve, 10));
+		}
+
+		writeHugoFiles(JSON.stringify({ ...files, "cc-env": env }));
+	}
+}