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

package/integrations/hugo/renderer/main.go

@@ -0,0 +1,412 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log"
+	"path/filepath"
+	"strings"
+	"syscall/js"
+	_ "time/tzdata"
+
+	"github.com/fsnotify/fsnotify"
+	"github.com/gohugoio/hugo/common/hmaps"
+	"github.com/gohugoio/hugo/config"
+	"github.com/gohugoio/hugo/config/allconfig"
+	"github.com/gohugoio/hugo/deps"
+	"github.com/gohugoio/hugo/hugofs"
+	"github.com/gohugoio/hugo/hugolib"
+	"github.com/gohugoio/hugo/parser/metadecoders"
+	"github.com/gohugoio/hugo/resources/page"
+	"github.com/spf13/afero"
+)
+
+// dispatchView is the view renderBatch executes for each batch: the batch's
+// requests arrive as template data (keyed by render id), and each request's
+// partial renders with `page` bound through the execution context, keying
+// every result with its request id for the browser to demultiplex.
+const dispatchView = `{{- with .cc_requests -}}
+  {{- /* cc_requests is a MAP keyed by render id, prepared on the Go side with
+     Hugo's params preparation: it recurses into nested maps (not arrays),
+     keeping case-insensitive Params semantics for props. Range order is
+     key-sorted; the browser demuxes by id, not position. */ -}}
+  {{- range $id, $req := . -}}
+    {{- $partial := $req.partial -}}
+    {{- $found := templates.Exists (printf "partials/%s" $partial) -}}
+    {{- $found = or $found (templates.Exists (printf "partials/%s.html" $partial)) -}}
+    {{- $found = or $found (templates.Exists (printf "partials/%s.htm" $partial)) -}}
+    {{- if not $found -}}
+      <div data-cc-render="{{ $id }}"><cc-missing-partial data-name="{{ $partial }}"></cc-missing-partial></div>
+    {{- else -}}
+      <div data-cc-render="{{ $id }}">{{- $result := try (partial $partial $req.props) -}}
+      {{- if $result.Err -}}
+        <cc-failed-partial data-name="{{ $partial }}" data-message="{{ $result.Err }}"></cc-failed-partial>
+      {{- else -}}
+        {{- $result.Value -}}
+      {{- end -}}</div>
+    {{- end -}}
+  {{- end -}}
+{{- end -}}`
+
+const dispatchViewPath = "/_default/__cc-dispatch.html"
+
+type editorSiteBuilder struct {
+	Cfg          *allconfig.Configs
+	Afs          afero.Fs
+	Fs           *hugofs.Fs
+	Sites        *hugolib.HugoSites
+	changedFiles []string
+	removedFiles []string
+}
+
+func editorFlags() config.Provider {
+	flags := config.New()
+	flags.Set("disableKinds", []string{"taxonomy", "term", "RSS", "sitemap", "robotsTXT", "404"})
+	flags.Set("cascade", []interface{}{
+		map[string]interface{}{
+			"build": map[string]interface{}{"render": "link"},
+		},
+	})
+	return flags
+}
+
+func (builder *editorSiteBuilder) loadConfig() error {
+	env := "production"
+	if contents, err := builder.readFile("cc-env"); err == nil {
+		env = strings.TrimSpace(contents)
+	}
+	cfg, err := allconfig.LoadConfig(allconfig.ConfigSourceDescriptor{
+		Fs:          builder.Afs,
+		Flags:       editorFlags(),
+		ConfigDir:   "config",
+		Environment: env,
+		// Only mirrored modules (theme, vendored) can resolve in the in-memory fs;
+		// skip imports whose replacement points at the repo on disk.
+		IgnoreModuleDoesNotExist: true,
+	})
+	if err != nil {
+		return err
+	}
+
+	// Rebuilds run through Hugo's incremental change-event pipeline, so enable
+	// Running/Watch and propagate to per-language configs (read by the `hugo.*`
+	// template namespace).
+	cfg.Base.WorkingDir = ""
+	cfg.Base.Internal.Running = true
+	cfg.Base.Internal.Watch = true
+
+	for _, languageConfig := range cfg.LanguageConfigMap {
+		languageConfig.Internal.Running = true
+		languageConfig.Internal.Watch = true
+		languageConfig.Build.BuildStats.Enable = false
+		if languageConfig.Params == nil {
+			languageConfig.Params = hmaps.Params{}
+		}
+		languageConfig.Params["env_client"] = true
+	}
+	builder.Cfg = cfg
+	builder.Fs = hugofs.NewFrom(builder.Afs, cfg.GetFirstLanguageConfig().BaseConfig())
+
+	return nil
+}
+
+func (builder *editorSiteBuilder) createSites() error {
+	if err := builder.loadConfig(); err != nil {
+		return fmt.Errorf("failed to load config: %w", err)
+	}
+
+	builder.Fs.PublishDir = hugofs.NewCreateCountingFs(builder.Fs.PublishDir)
+
+	sites, err := hugolib.NewHugoSites(deps.DepsCfg{
+		Fs:      builder.Fs,
+		Configs: builder.Cfg,
+	})
+	if err != nil {
+		return fmt.Errorf("failed to create sites: %w", err)
+	}
+	builder.Sites = sites
+
+	return nil
+}
+
+func (builder *editorSiteBuilder) build() error {
+	var events []fsnotify.Event
+	if builder.Sites == nil {
+		if err := builder.createSites(); err != nil {
+			return err
+		}
+	} else {
+		events = builder.changeEvents()
+	}
+
+	err := builder.Sites.Build(hugolib.BuildCfg{NoBuildLock: true}, events...)
+	if err != nil {
+		return err
+	}
+
+	builder.changedFiles = nil
+	builder.removedFiles = nil
+
+	if n := builder.Sites.NumLogErrors(); n > 0 {
+		err = fmt.Errorf("logged %d errors", n)
+	}
+	return err
+}
+
+// buildIfDirty runs the initial build when the site doesn't exist yet, then
+// an incremental build only when files changed since the last build, so
+// renders with nothing pending skip the build entirely.
+func (builder *editorSiteBuilder) buildIfDirty() error {
+	if builder.Sites == nil {
+		return builder.build()
+	}
+
+	if len(builder.changedFiles) == 0 && len(builder.removedFiles) == 0 {
+		return nil
+	}
+
+	if err := builder.build(); err != nil {
+		return fmt.Errorf("build after pending content changes: %w", err)
+	}
+	return nil
+}
+
+func (builder *editorSiteBuilder) writeFile(filename, content string) {
+	filename = normalizeMemfsPath(filename)
+	if err := afero.WriteFile(builder.Afs, filepath.FromSlash(filename), []byte(content), 0755); err != nil {
+		fmt.Println(fmt.Sprintf("Failed to write file: %s", err))
+		return
+	}
+
+	builder.changedFiles = append(builder.changedFiles, filename)
+}
+
+func (builder *editorSiteBuilder) removeFile(filename string) {
+	filename = normalizeMemfsPath(filename)
+	if err := builder.Afs.Remove(filename); err != nil {
+		fmt.Println(fmt.Sprintf("Failed to remove file: %s", err))
+		return
+	}
+
+	// Publish-dir files aren't Hugo source files, so their removal shouldn't
+	// be fed back in as a change event.
+	if !strings.HasPrefix(filepath.ToSlash(filename), "public/") {
+		builder.removedFiles = append(builder.removedFiles, filename)
+	}
+}
+
+func (builder *editorSiteBuilder) readFile(filename string) (string, error) {
+	filename = normalizeMemfsPath(filename)
+	b, err := afero.ReadFile(builder.Afs, filepath.Clean(filename))
+	if err != nil {
+		return "", err
+	}
+	return string(b), nil
+}
+
+func (builder *editorSiteBuilder) changeEvents() []fsnotify.Event {
+	var events []fsnotify.Event
+
+	for _, v := range builder.changedFiles {
+		events = append(events, fsnotify.Event{
+			Name: v,
+			Op:   fsnotify.Write,
+		})
+	}
+
+	for _, v := range builder.removedFiles {
+		events = append(events, fsnotify.Event{
+			Name: v,
+			Op:   fsnotify.Remove,
+		})
+	}
+
+	return events
+}
+
+// normalizeMemfsPath maps the browser's site-root-relative source paths
+// ("/content/blog/one.md") to the in-memory fs's slash-less relative form,
+// which Hugo's contentDir/dataDir/layoutDir also use.
+func normalizeMemfsPath(p string) string {
+	return strings.TrimPrefix(filepath.ToSlash(p), "/")
+}
+
+var builder editorSiteBuilder
+
+func main() {
+	builder = editorSiteBuilder{Afs: afero.NewMemMapFs()}
+
+	log.SetOutput(io.Discard)
+
+	c := make(chan struct{}, 0)
+	js.Global().Set("writeHugoFiles", js.FuncOf(writeHugoFiles))
+	js.Global().Set("removeHugoFiles", js.FuncOf(removeHugoFiles))
+	js.Global().Set("readHugoFiles", js.FuncOf(readHugoFiles))
+	js.Global().Set("initHugoEditorSite", js.FuncOf(initHugoEditorSite))
+	js.Global().Set("renderHugoPartials", js.FuncOf(renderHugoPartials))
+	<-c
+}
+
+func errorValue(format string, args ...interface{}) js.Value {
+	return js.ValueOf(map[string]interface{}{
+		"error": fmt.Sprintf(format, args...),
+	})
+}
+
+func writeHugoFiles(this js.Value, args []js.Value) interface{} {
+	var writeFiles map[string]string
+	if err := json.Unmarshal([]byte(args[0].String()), &writeFiles); err != nil {
+		return errorValue("bad writeHugoFiles payload: %s", err)
+	}
+
+	for fileName, fileContents := range writeFiles {
+		builder.writeFile(fileName, fileContents)
+	}
+	return nil
+}
+
+func removeHugoFiles(this js.Value, args []js.Value) interface{} {
+	var removeFiles []string
+	if err := json.Unmarshal([]byte(args[0].String()), &removeFiles); err != nil {
+		return errorValue("bad removeHugoFiles payload: %s", err)
+	}
+
+	for _, fileName := range removeFiles {
+		builder.removeFile(fileName)
+	}
+	return nil
+}
+
+func readHugoFiles(this js.Value, args []js.Value) interface{} {
+	var readFiles []string
+	if err := json.Unmarshal([]byte(args[0].String()), &readFiles); err != nil {
+		return errorValue("bad readHugoFiles payload: %s", err)
+	}
+
+	fileContents := make(map[string]interface{})
+	for _, fileName := range readFiles {
+		contents, err := builder.readFile(fileName)
+		if err != nil {
+			continue
+		}
+		fileContents[fileName] = contents
+	}
+
+	return js.ValueOf(fileContents)
+}
+
+func initHugoEditorSite(this js.Value, args []js.Value) interface{} {
+	if err := builder.loadConfig(); err != nil {
+		return errorValue("failed to load config: %s", err)
+	}
+
+	builder.writeFile(filepath.Join(
+		builder.Cfg.Base.LayoutDir, "_default", "__cc-dispatch.html"), dispatchView)
+	return nil
+}
+
+// renderRequests is the browser's queued batch: the one render target every
+// request shares, plus the requests to render against it.
+type renderRequests struct {
+	Target   string          `json:"target"`
+	Requests []renderRequest `json:"requests"`
+}
+
+type renderRequest struct {
+	ID      string          `json:"id"`
+	Partial string          `json:"partial"`
+	Props   json.RawMessage `json:"props"`
+}
+
+func (builder *editorSiteBuilder) targetPage(target string) page.Page {
+	target = normalizeMemfsPath(target)
+	if target != "" && builder.Sites != nil {
+		for _, s := range builder.Sites.Sites {
+			for _, p := range s.Pages() {
+				f := p.File()
+				if f == nil {
+					continue
+				}
+				if filepath.Join(builder.Cfg.Base.ContentDir, f.Path()) != target {
+					continue
+				}
+				return p
+			}
+		}
+	}
+	return nil
+}
+
+func renderHugoPartials(this js.Value, args []js.Value) interface{} {
+	var payload renderRequests
+	if err := json.Unmarshal([]byte(args[0].String()), &payload); err != nil {
+		return errorValue("bad renderHugoPartials payload: %s", err)
+	}
+	reqs := payload.Requests
+	if len(reqs) == 0 {
+		return errorValue("renderHugoPartials requires at least one request")
+	}
+	if err := builder.buildIfDirty(); err != nil {
+		return errorValue("editor site build failed: %s", err)
+	}
+
+	for _, req := range reqs {
+		if req.Partial == "" {
+			return errorValue("renderHugoPartials requires a \"partial\" name on every request")
+		}
+	}
+
+	html, err := builder.renderBatch(payload.Target, reqs)
+	if err != nil {
+		return errorValue("%s", err)
+	}
+
+	return js.ValueOf(map[string]interface{}{
+		"html": html,
+	})
+}
+
+func (builder *editorSiteBuilder) renderBatch(target string, reqs []renderRequest) (string, error) {
+	requests := make(map[string]interface{}, len(reqs))
+	for _, req := range reqs {
+		var props interface{}
+		if len(req.Props) > 0 {
+			if err := json.Unmarshal(req.Props, &props); err != nil {
+				return "", fmt.Errorf("bad props for %s: %s", req.Partial, err)
+			}
+		}
+		requests[req.ID] = map[string]interface{}{
+			"partial": req.Partial,
+			"props":   props,
+		}
+	}
+	// Decode the batch through Hugo's YAML decoder so props decode with identical types
+	encoded, err := json.Marshal(requests)
+	if err != nil {
+		return "", fmt.Errorf("failed to encode render batch: %s", err)
+	}
+	decoded, err := metadecoders.Decoder{}.UnmarshalToMap(encoded, metadecoders.YAML)
+	if err != nil {
+		return "", fmt.Errorf("failed to decode render batch: %s", err)
+	}
+	hmaps.PrepareParams(decoded)
+
+	renderTarget := builder.targetPage(target)
+	if renderTarget == nil {
+		renderTarget = page.NopPage
+	}
+	store := builder.Sites.GetTemplateStore()
+	ctx := store.PrepareTopLevelRenderCtx(context.Background(), renderTarget)
+	tmpl := store.LookupByPath(dispatchViewPath)
+	if tmpl == nil {
+		return "", fmt.Errorf("dispatch view %q not found", dispatchViewPath)
+	}
+	var out strings.Builder
+	if err := store.ExecuteWithContext(ctx, tmpl, &out,
+		map[string]interface{}{"cc_requests": decoded}); err != nil {
+		return "", fmt.Errorf("failed to render the dispatch view for %q: %w", target, err)
+	}
+	return out.String(), nil
+}

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);