@cloudcannon/editable-regions 0.0.18 → 0.0.19

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/liquid/README.md

@@ -16,6 +16,7 @@ build time; this directory is what that bundle pulls in.
   - [Eleventy global](#eleventy-global)
   - [`pkg` global](#pkg-global)
 - [Filters](#filters)
+  - [What the auto-mirror actually does](#what-the-auto-mirror-actually-does)
   - [Adding a custom filter](#adding-a-custom-filter)
   - [Overriding a built-in](#overriding-a-built-in)
 - [Shortcodes and paired shortcodes](#shortcodes-and-paired-shortcodes)
@@ -49,6 +50,20 @@ not implemented — see "Limitations and fallbacks".
 npm install @cloudcannon/editable-regions
 ```
 
+Requires **Node 20.19+ or 22.12+**. The plugin is an ES module; those are the
+releases where Node can `require()` one, so a CommonJS config can pull it in
+with a plain `require`. On anything older, use a dynamic import from an async
+config instead:
+
+```js
+module.exports = async function (eleventyConfig) {
+  const { default: editableRegions } = await import(
+    "@cloudcannon/editable-regions/eleventy"
+  );
+  eleventyConfig.addPlugin(editableRegions);
+};
+```
+
 Wire the plugin into your `eleventy.config.mjs`. The minimal case is one
 line — Liquid is the plugin's default language and is enabled implicitly:
 
@@ -127,7 +142,7 @@ works too.
 | `liquid.pairedShortcodes` | Same as `shortcodes`, for paired shortcodes. |
 | `liquid.tags` | Map of tag name → factory module path. Browser-side override. Tags auto-mirror from the config like filters/shortcodes; use this only for a tag that can't run in the browser as written. |
 | `liquid.configPath` | Path to the Eleventy config file to import and replay for the auto-mirror, relative to the project root. Defaults to the first of 11ty's standard names that exists (`.eleventy.js`, `eleventy.config.{js,mjs,cjs}`). Set only if you run Eleventy with a non-default `--config`. |
-| `liquid.browserStub` | Extra bare module specifiers to stub out of the browser bundle, on top of the 11ty toolchain and Node built-ins (always stubbed). Use when the config imports a native/Node-only package (e.g. `sharp`) that no browser-bound helper actually calls. |
+| `liquid.browserStub` | Extra bare module specifiers to stub out of the browser bundle, on top of the 11ty toolchain and Node built-ins (always stubbed). Use for a native/Node-only package (e.g. `sharp`, or a Node-only 11ty plugin) that would otherwise break bundling, or whose config-time calls would abort the auto-mirror. See "What the auto-mirror actually does". |
 
 ## How it fits together
 
@@ -151,7 +166,7 @@ Globals are passed to `new Liquid({ globals })` inside `createSharedLiquidEngine
 
 | Global | Status | Notes |
 | --- | --- | --- |
-| `collections` | Implemented | `Proxy` that lazily resolves `collections.foo` to an array of items via the Visual Editor API. Items shaped roughly like Eleventy's: `{ url, inputPath, data }`. |
+| `collections` | Implemented | Object with one lazy getter per collection name, resolving `collections.foo` to an array of items via the Visual Editor API. Items shaped roughly like Eleventy's: `{ url, inputPath, data }`. Listing the collections is a single API call; a collection's files are fetched only when a template reads that key, with bounded concurrency, and cached until the collection changes. A component that never mentions `collections` issues no per-file requests. |
 | `ENV_CLIENT` | Implemented | Always `true` in this bundle. Templates can branch on it to opt out of build-only logic. |
 | `page` | Partial | `Proxy` backed by `CloudCannon.currentFile()`. See below for which properties are supported. |
 | custom globals | Opt-in | Whatever you pass via `pluginOptions.globals` (e.g. an `env` object), embedded at build time. See "Custom globals" below. |
@@ -260,6 +275,15 @@ name collision: **built-ins**, **auto-mirrored**, then **overrides**.
    at render time will throw when invoked in the browser — the signal to add
    an override.
 
+   `async` configs and `async` plugins are supported: the replay is awaited,
+   and component rendering is held until it finishes. This matters because
+   `await import("@11ty/eleventy")` — the usual way a CommonJS config reaches
+   the ESM-only `RenderPlugin` / `I18nPlugin` exports — makes the whole config
+   async, and none of its helpers exist until that import settles.
+
+   See "What the auto-mirror actually does" below before assuming a helper
+   will survive the trip.
+
 3. **Overrides** (`pluginOptions.liquid.filters`). A map from filter name to
    module path. Two reasons to use this:
    - **A mirrored filter throws at render time** — supply a browser-safe
@@ -269,6 +293,69 @@ name collision: **built-ins**, **auto-mirrored**, then **overrides**.
      `eleventyConfig.addFilter("url", …)` won't reach live editing unless you
      also register it here.
 
+### What the auto-mirror actually does
+
+The mirror is **not** a static scan of your config. The bundle imports your
+real config module and *runs it* in the browser, against a stand-in
+`eleventyConfig` that records `addFilter` / `addShortcode` / `addLiquidTag`
+calls and ignores everything else. That's what makes closures and imports
+survive — and it means every line of your config executes in a browser.
+
+Most of what that implies is handled for you:
+
+- **Node built-ins and the 11ty toolchain are stubbed**, so importing them is
+  harmless. A stubbed module that gets *called* during the replay is skipped
+  with a console warning and the rest of the config still mirrors; the same
+  call from inside a rendered helper throws, because there it's a real
+  problem you need to fix.
+- **Node globals are shimmed.** `process.env.X`, `process.cwd()`, `__dirname`
+  and `__filename` resolve to inert values rather than a `ReferenceError`.
+  `process.env.NODE_ENV` reads `"development"`, for the same reason
+  `eleventy.env.runMode` is `"serve"` — the editor isn't a production build,
+  and a config gated on `NODE_ENV === "production"` shouldn't drag build-only
+  plugins into the mirror. Real values belong in `pluginOptions.globals`.
+
+What's left is code that runs at config time and needs something the browser
+genuinely doesn't have. In rough order of what to reach for:
+
+1. **`pluginOptions.liquid.browserStub`** — the usual answer. Add the module
+   specifier and it resolves to a stub, so calls through it are skipped
+   instead of aborting the replay. This is what a Node-only plugin needs,
+   including the argument-side case that nothing else can intercept:
+
+   ```js
+   // `pluginBookshop({...})` is evaluated *before* `addPlugin` is called, so
+   // no amount of proxying `eleventyConfig` can catch it — the module itself
+   // has to be stubbed.
+   eleventyConfig.addPlugin(pluginBookshop({ /* Node-only */ }));
+
+   eleventyConfig.addPlugin(editableRegions, {
+     liquid: { browserStub: ["@bookshop/eleventy-bookshop"] },
+   });
+   ```
+
+2. **A per-helper override** (`pluginOptions.liquid.filters` / `.shortcodes` /
+   `.pairedShortcodes` / `.tags`) — for a helper that mirrors fine but can't
+   *run* in the browser. See "Adding a custom filter".
+
+3. **An early return** — last resort, for config-time code that sits behind no
+   import at all, so there's nothing to stub:
+
+   ```js
+   export default function (eleventyConfig) {
+     eleventyConfig.addFilter("shout", (s) => String(s).toUpperCase());
+
+     // Everything below is build-only; the browser mirror stops here.
+     if (typeof window !== "undefined") return;
+
+     const manifest = buildManifestFromDisk();
+     eleventyConfig.addGlobalData("manifest", manifest);
+   }
+   ```
+
+   Put it as late as you can: helpers registered *above* the return still
+   mirror, and anything below it won't be available in live editing.
+
 ### Adding a custom filter
 
 For most filters you don't need to do anything — registering with Eleventy
@@ -540,7 +627,9 @@ section catalogues the gaps and the patterns for working around them.
 | `htmlBaseUrl`, `serverlessUrl` filters | Registered as warn-once pass-throughs; return their input unchanged. `htmlBaseUrl` depends on the configured `pathPrefix` (we don't expose it yet); `serverlessUrl` is a build-time concept with no editor equivalent. | Override via `pluginOptions.liquid.filters` if you have a browser-safe equivalent. Otherwise wrap the template path in `{% if ENV_CLIENT %}` and skip it. |
 | `inputPathToUrl` filter when the source file wasn't in the last build | Falls back to warn-once and returns the input path unchanged. The build-time page map is what makes this filter work; for files added since the last build there's no URL to look up. | Re-build to pick up new pages. |
 | `renderTemplate` / `renderFile` / `renderContent` with a non-Liquid engine arg (e.g. `"njk"`, `"md"`) | Warn-once and return the body unchanged. We only ship LiquidJS in the bundle. | Switch the template to Liquid, or guard the call with `{% if ENV_CLIENT %}` so it only runs at build time. |
-| Mirrored filters/shortcodes that touch `this.ctx`, `process`, `require`, `__dirname`, or a closed-over Node import | Auto-mirror ships them verbatim; they throw at render time in the browser. The thrown error is wrapped by `enhanceLiquidError` with the filter/shortcode name. | Add a `pluginOptions.liquid.filters` (or `.shortcodes` / `.pairedShortcodes`) override pointing at a browser-safe replacement. |
+| Mirrored filters/shortcodes that touch `this.ctx` or a closed-over Node import | Auto-mirror ships them verbatim; they throw at render time in the browser. The thrown error is wrapped by `enhanceLiquidError` with the filter/shortcode name. | Add a `pluginOptions.liquid.filters` (or `.shortcodes` / `.pairedShortcodes`) override pointing at a browser-safe replacement. |
+| Mirrored helpers that read `process.env`, `process.cwd()`, `__dirname` or `__filename` | Don't throw — they read the shim (see "What the auto-mirror actually does"), so they render, but with placeholder values rather than the build's. | If the value matters, pass it through `pluginOptions.globals` and read it as a Liquid global, or override the helper. |
+| `{{ collections \| json }}` — serialising the **whole** collections object | Renders `{"posts":{},"pages":{}}`. Each key is a lazy getter resolving to a Promise, and `JSON.stringify` can't await; every other access pattern is unaffected because LiquidJS *does* await during expression evaluation. Materialising for serialisation would mean fetching every file in every collection on any access, which is what the laziness exists to prevent. | Serialise one collection at a time — `{{ collections.posts \| json }}` works normally. |
 | Helpers from auto-loaded 11ty plugins used **inside a component** (e.g. `getBundle` / `getBundleFileUrl` / `renderTransforms` from `@11ty/eleventy-plugin-bundle`) | 11ty 3.x auto-loads several plugins that register universal helpers; the auto-mirror ships them verbatim and they'll throw if invoked from a template the editor re-renders. Layouts and pages aren't affected — the live runtime only renders components. | If you reference one of these in an editable component, add a browser-safe override via `pluginOptions.liquid.shortcodes` / `.filters`. Most users won't hit this because bundle helpers typically live in layouts. |
 | User overrides of a **built-in** filter name via `eleventyConfig.addFilter` | The auto-mirror skips built-in names, so the override doesn't reach the bundle — live editing keeps using our handwritten port. | Also register the override in `pluginOptions.liquid.filters`. See "Overriding a built-in". |
 | Custom Liquid tags | Not auto-mirrored. Templates referencing an unregistered custom tag will fail with an enhanced "tag X not found" error. | Register every tag you want available via `pluginOptions.liquid.tags`. |

package/integrations/liquid/errors.mjs

@@ -8,7 +8,9 @@
 export function enhanceLiquidError(err, componentName) {
 	const message = err instanceof Error ? err.message : String(err);
 
-	const unknownFilter = message.match(/undefined filter[:.]?\s*(\S+)/i);
+	// LiquidJS appends its own position suffix ("undefined filter: foo, line:2,
+	// col:1"), so stop at the comma rather than at whitespace.
+	const unknownFilter = message.match(/undefined filter[:.]?\s*([^\s,]+)/i);
 	if (unknownFilter) {
 		const filterName = unknownFilter[1];
 		return new Error(

package/integrations/liquid/fs.mjs

@@ -1,5 +1,13 @@
 import { log, warn } from "./logger.mjs";
 
+/**
+ * Matches `path.extname`: last dot of the final segment, leading dot excluded.
+ */
+function hasExtension(/** @type {string} */ filePath) {
+	const basename = filePath.slice(filePath.lastIndexOf("/") + 1);
+	return basename.lastIndexOf(".") > 0;
+}
+
 /**
  * In-memory filesystem for LiquidJS, reading from `window.cc_liquid_files`.
  * @type {any}
@@ -60,7 +68,9 @@ export const inMemoryFs = {
 		/** @type {string} */ ext,
 	) {
 		const extension = ext || ".liquid";
-		const fileWithExt = file.endsWith(extension) ? file : `${file}${extension}`;
+		// Only append when the file has none, as LiquidJS's Node fs does —
+		// otherwise `include "card.html"` becomes `card.html.liquid`.
+		const fileWithExt = hasExtension(file) ? file : `${file}${extension}`;
 		const normalizedRoot = root.replace(/^\.\//, "").replace(/\/*$/, "/");
 		const resolved = `${normalizedRoot}${fileWithExt}`;
 		log("resolve:", { root, file, ext }, "->", resolved);

package/integrations/liquid/globals.mjs

@@ -1,6 +1,7 @@
 // Builders for the `page` and `collections` globals on the shared Liquid
-// engine. Both return Promises that LiquidJS awaits at the globals level;
-// property access in templates is then synchronous on the resolved objects.
+// engine. Both return Promises that LiquidJS awaits at the globals level.
+// `page` resolves to a plain object; `collections` resolves to an object whose
+// keys are lazy getters, so a template only pays for the collections it reads.
 
 import { apiLoadedPromise, CloudCannon } from "../../helpers/cloudcannon.mjs";
 import { getPageMap, normalizeInputPath } from "./page-map.mjs";
@@ -150,27 +151,74 @@ export async function buildPageData() {
 	};
 }
 
-/** @type {Promise<Record<string, Array<any>>> | null} */
+/**
+ * Ceiling on concurrent `file.data.get()` calls. One call per file over a
+ * collection of thousands fails with `ERR_INSUFFICIENT_RESOURCES` — a net-stack
+ * error, so each resolves to a request somewhere behind the editor API.
+ */
+const MATERIALISE_CONCURRENCY = 24;
+
+/**
+ * `Promise.all(items.map(fn))` with at most `limit` calls in flight. Results
+ * keep their input order.
+ *
+ * @template T, R
+ * @param {T[]} items
+ * @param {(item: T) => Promise<R>} fn
+ * @param {number} limit
+ * @returns {Promise<R[]>}
+ */
+async function mapWithConcurrency(items, fn, limit) {
+	/** @type {R[]} */
+	const results = new Array(items.length);
+	let cursor = 0;
+
+	const worker = async () => {
+		while (cursor < items.length) {
+			const index = cursor++;
+			results[index] = await fn(items[index]);
+		}
+	};
+
+	await Promise.all(
+		Array.from({ length: Math.min(limit, items.length) }, worker),
+	);
+	return results;
+}
+
+/** One `CloudCannon.collections()` call, keyed by name. @type {Promise<Map<string, any>> | null} */
+let collectionIndexCache = null;
+
+/** Materialised items, per collection name. @type {Map<string, Promise<any[]>>} */
+const collectionItemsCache = new Map();
+
+/** @type {Promise<Record<string, any>> | null} */
 let collectionsCache = null;
 
 /** @type {Array<{ target: any, event: "change" | "delete", handler: () => void }>} */
 let collectionsSubscriptions = [];
 
 /**
- * Builds (or returns cached) the `collections` object, keyed by collection
- * name. Subscribes to `change`/`delete` on each collection and drops the cache
- * when either fires, so edits during a session are picked up on the next render.
+ * Enumerates the site's collections — one API call, cached — and subscribes to
+ * `change`/`delete` on each so an edit drops the caches. Never calls
+ * `collection.items()`: knowing the *names* is what lets the getters be
+ * enumerable without fetching behind them.
  *
- * @returns {Promise<Record<string, Array<any>>>}
+ * @returns {Promise<Map<string, any>>}
  */
-export function buildCollectionsData() {
-	if (!collectionsCache) {
-		collectionsCache = (async () => {
+function loadCollectionIndex() {
+	if (!collectionIndexCache) {
+		collectionIndexCache = (async () => {
 			await apiLoadedPromise;
 			const allCollections = await CloudCannon?.collections?.();
-			if (!allCollections?.length) return {};
+
+			/** @type {Map<string, any>} */
+			const index = new Map();
+			if (!allCollections?.length) return index;
 
 			for (const collection of allCollections) {
+				index.set(collection.collectionKey, collection);
+
 				const handler = () => resetCollectionsCache();
 				collection.addEventListener("change", handler);
 				collection.addEventListener("delete", handler);
@@ -179,31 +227,82 @@ export function buildCollectionsData() {
 					{ target: collection, event: "delete", handler },
 				);
 			}
+			return index;
+		})();
+	}
+	return collectionIndexCache;
+}
+
+/**
+ * Materialises one collection's files, memoised per name — the only place that
+ * issues per-file requests. An unknown name is `[]`, matching 11ty.
+ *
+ * @param {string} key
+ * @returns {Promise<any[]>}
+ */
+function loadCollectionItems(key) {
+	let items = collectionItemsCache.get(key);
+	if (!items) {
+		items = (async () => {
+			const collection = (await loadCollectionIndex()).get(key);
+			if (!collection) return [];
 
-			const entries = await Promise.all(
-				allCollections.map(async (collection) => {
-					const key = collection.collectionKey;
-					let files;
-					try {
-						files = await collection.items();
-					} catch {
-						return /** @type {[string, any[]]} */ ([key, []]);
-					}
-					const items = await Promise.all(files.map(materialiseFile));
-					return /** @type {[string, any[]]} */ ([key, items]);
-				}),
+			let files;
+			try {
+				files = await collection.items();
+			} catch {
+				return [];
+			}
+			return mapWithConcurrency(
+				files,
+				materialiseFile,
+				MATERIALISE_CONCURRENCY,
 			);
-			return Object.fromEntries(entries);
+		})();
+		collectionItemsCache.set(key, items);
+	}
+	return items;
+}
+
+/**
+ * Builds (or returns cached) the `collections` object. Every key is a lazy
+ * getter returning a `Promise` of its items, which LiquidJS awaits during
+ * expression evaluation — so a component that never mentions `collections`
+ * issues no per-file requests.
+ *
+ * Getters not a Proxy: LiquidJS probes `next` and `toLiquid` on every object
+ * it resolves, and a blanket-getter Proxy answers those with a Promise, which
+ * breaks the lookup entirely.
+ *
+ * @returns {Promise<Record<string, any>>}
+ */
+export function buildCollectionsData() {
+	if (!collectionsCache) {
+		collectionsCache = (async () => {
+			const index = await loadCollectionIndex();
+
+			/** @type {Record<string, any>} */
+			const collections = {};
+			for (const key of index.keys()) {
+				Object.defineProperty(collections, key, {
+					enumerable: true,
+					configurable: true,
+					get: () => loadCollectionItems(key),
+				});
+			}
+			return collections;
 		})();
 	}
 	return collectionsCache;
 }
 
-/** Clears the collections cache and tears down its invalidation listeners. */
+/** Clears every collections cache and tears down the invalidation listeners. */
 export function resetCollectionsCache() {
 	for (const { target, event, handler } of collectionsSubscriptions) {
 		target.removeEventListener(event, handler);
 	}
 	collectionsSubscriptions = [];
+	collectionIndexCache = null;
+	collectionItemsCache.clear();
 	collectionsCache = null;
 }

package/integrations/liquid/index.mjs

@@ -73,8 +73,11 @@ export function registerLiquidComponent(key, contents) {
 /**
  * Wraps `window.cc_components` in a Proxy that resolves any component name on
  * demand via `{% include %}` — the primary resolution path. Names registered
- * via `registerLiquidComponent` take precedence. Call after
- * `createSharedLiquidEngine()`.
+ * via `registerLiquidComponent` take precedence.
+ *
+ * Call after `createSharedLiquidEngine()` and last of the `register*` calls:
+ * publishing `cc_components` is what tells the editor every helper is in
+ * place, and an empty one reads as a missing registration script.
  *
  * @returns {void}
  */

package/integrations/vue.mjs

@@ -0,0 +1,28 @@
+import { createApp, h } from "vue";
+import { addEditableComponentRenderer } from "../helpers/cloudcannon.mjs";
+
+/**
+ * Registers a Vue component with the CloudCannon component system.
+ * Creates a wrapper that renders the Vue component to an HTMLElement.
+ *
+ * @param {string} key - Unique identifier for the component
+ * @param {any} component - The Vue component to register
+ * @returns {void}
+ */
+export const registerVueComponent = (key, component) => {
+	/**
+	 * Wrapper function that renders the Vue component to an HTMLElement.
+	 *
+	 * @param {any} props - Props to pass to the Vue component
+	 * @returns {HTMLElement} The rendered component as an HTMLElement
+	 */
+	const wrappedComponent = (props) => {
+		const rootEl = document.createElement("div");
+		const app = createApp({ render: () => h(component, props) });
+		app.mount(rootEl);
+
+		return rootEl;
+	};
+
+	addEditableComponentRenderer(key, wrappedComponent);
+};

package/nodes/editable-array-item.ts

@@ -1,7 +1,6 @@
 import "../components/ui/editable-array-item-controls.js";
 import type EditableArrayItemControls from "../components/ui/editable-array-item-controls.js";
 import {
-	hasEditableArrayItem,
 	isEditableArray,
 	isEditableArrayItem,
 	isEditableElement,
@@ -10,6 +9,12 @@ import { CloudCannon, realizeAPIValue } from "../helpers/cloudcannon.mjs";
 import type EditableArray from "./editable-array.js";
 import EditableComponent from "./editable-component.js";
 
+export const hasEditableArrayItem = <T extends object>(
+	el: T,
+): el is T & { editable: EditableArrayItem } => {
+	return "editable" in el && el.editable instanceof EditableArrayItem;
+};
+
 export default class EditableArrayItem extends EditableComponent {
 	parent: EditableArray | null = null;
 

package/nodes/editable-component.ts

@@ -1,11 +1,10 @@
 import {
 	areEqualEditables,
-	hasEditable,
-	hasEditableText,
 	isEditableElement,
 	isEditableText,
 } from "../helpers/checks.js";
-import Editable from "./editable.js";
+import Editable, { hasEditable } from "./editable.js";
+import { hasEditableText } from "./editable-text.js";
 import "../components/ui/editable-region-error-card.js";
 import "../components/ui/editable-component-controls.js";
 import type EditableComponentControls from "../components/ui/editable-component-controls.js";