From 5ef4696a1bdea797469b72d20eead16dd5839119 Mon Sep 17 00:00:00 2001
From: Romain Gauthier <contact@romain.pm>
Date: Fri, 24 Jul 2026 22:10:22 +0200
Subject: [PATCH 1/2] feat(engine): report failing views with source-mapped
 stack traces
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When a view threw, Jahia replaced the fragment with an HTML comment and
logged an exception whose JavaScript frames pointed inside the module's
bundle (`dist/server/index.js:3937`). Both halves of that are unhelpful: the
failure is invisible on the page unless you read the source, and the stack
does not say which file you wrote is at fault.

The engine now reads the source map the build already emits next to a
module's server bundle, and rewrites JS frames back to module sources —
`src/components/Foo/default.server.tsx:12`. Maps are parsed on first use and
dropped when a module is unregistered, so a redeploy picks up new sources.
Frames without a map (the library, the engine itself) are left untouched.

In development mode a failing view also renders a visible, HTML-escaped error
box in place of its fragment, carrying the message and the mapped stack. In
production the exception propagates exactly as before; only the new log line
is added.

Verified on two Jahia 8.2 instances, one in each mode, against the test
module's crashing view: the box appears in development with the frame mapped
to TestCrashingView.tsx:11 (the failing line), production output is unchanged,
and both modes log the mapped trace. Nine unit tests cover the VLQ decoding,
segment lookup and frame rewriting.

Closes #700
---
 .chachalog/Rt6yWm4L.md                        |   6 +
 .../1-dev-environment/README.md               |   6 +
 .../engine/jsengine/GraalVMEngine.java        |  12 +-
 .../modules/engine/jsengine/SourceMaps.java   | 270 ++++++++++++++++++
 .../modules/engine/views/JSScript.java        |  16 ++
 .../modules/engine/views/ViewRenderError.java |  85 ++++++
 .../engine/jsengine/SourceMapsTest.java       | 110 +++++++
 7 files changed, 503 insertions(+), 2 deletions(-)
 create mode 100644 .chachalog/Rt6yWm4L.md
 create mode 100644 javascript-modules-engine-java/src/main/java/org/jahia/modules/javascript/modules/engine/jsengine/SourceMaps.java
 create mode 100644 javascript-modules-engine-java/src/main/java/org/jahia/modules/javascript/modules/engine/views/ViewRenderError.java
 create mode 100644 javascript-modules-engine-java/src/test/java/org/jahia/modules/javascript/modules/engine/jsengine/SourceMapsTest.java

diff --git a/.chachalog/Rt6yWm4L.md b/.chachalog/Rt6yWm4L.md
new file mode 100644
index 00000000..cf4686d7
--- /dev/null
+++ b/.chachalog/Rt6yWm4L.md
@@ -0,0 +1,6 @@
+---
+# Allowed version bumps: patch, minor, major
+javascript-modules: minor
+---
+
+A view that throws now reports itself. In development mode the failing fragment is replaced by a visible error box holding the message and the stack trace, instead of an HTML comment that only the page source revealed. Stack traces — in the box and in the server log, in every mode — have their positions mapped back to the module's own sources through the source map shipped next to the server bundle, so frames read `src/components/Foo/default.server.tsx:12` rather than `dist/server/index.js:3937`. Production rendering is unchanged. (#700)
diff --git a/docs/1-getting-started/1-dev-environment/README.md b/docs/1-getting-started/1-dev-environment/README.md
index f9d45a45..24b36983 100644
--- a/docs/1-getting-started/1-dev-environment/README.md
+++ b/docs/1-getting-started/1-dev-environment/README.md
@@ -104,4 +104,10 @@ Now that your _template set_ (that's how we call a module that provides page tem
 
 Congratulations! You have successfully set up your development environment and created a new project in Jahia. In the next sections, we'll start building the project.
 
+## When a view fails
+
+The Docker instance above runs Jahia in development mode. When one of your views throws, the fragment it should have produced is replaced on the page by a red box carrying the error message and its stack trace, with positions mapped back to your own sources (`src/components/…/default.server.tsx:12`) rather than to the bundle the build produced. The rest of the page still renders, so a broken component does not take the whole page down.
+
+The same error is written to the server log, which you can follow with `docker compose logs -f jahia`. In production mode the box is not rendered — a live site keeps Jahia's default behaviour — but the log keeps the mapped stack trace.
+
 Next: [Making a Hero Section](making-a-hero-section)
diff --git a/javascript-modules-engine-java/src/main/java/org/jahia/modules/javascript/modules/engine/jsengine/GraalVMEngine.java b/javascript-modules-engine-java/src/main/java/org/jahia/modules/javascript/modules/engine/jsengine/GraalVMEngine.java
index 2baabd4f..4622e049 100644
--- a/javascript-modules-engine-java/src/main/java/org/jahia/modules/javascript/modules/engine/jsengine/GraalVMEngine.java
+++ b/javascript-modules-engine-java/src/main/java/org/jahia/modules/javascript/modules/engine/jsengine/GraalVMEngine.java
@@ -73,6 +73,7 @@ public class GraalVMEngine {
     private final ThreadLocal<Stack<ContextProvider>> currentContext = ThreadLocal.withInitial(Stack::new);
 
     private final Map<Bundle, Source> initScripts = Collections.synchronizedMap(new LinkedHashMap<>());
+    private final SourceMaps sourceMaps = new SourceMaps();
     private final AtomicInteger version = new AtomicInteger(0);
 
     private BundleContext bundleContext;
@@ -83,8 +84,9 @@ public BundleContext getBundleContext() {
 
     public void enableJavascriptModule(Bundle bundle) {
         try {
-            initScripts.put(bundle,
-                    getGraalSource(bundle, bundle.getHeaders().get(BUNDLE_HEADER_JAVASCRIPT_INIT_SCRIPT)));
+            String initScript = bundle.getHeaders().get(BUNDLE_HEADER_JAVASCRIPT_INIT_SCRIPT);
+            initScripts.put(bundle, getGraalSource(bundle, initScript));
+            sourceMaps.register(bundle, initScript);
             version.incrementAndGet();
             logger.info("Registered bundle {} in GraalVM engine", bundle.getSymbolicName());
         } catch (IOException ioe) {
@@ -94,11 +96,17 @@ public void enableJavascriptModule(Bundle bundle) {
 
     public void disableJavascriptModule(Bundle bundle) {
         if (initScripts.remove(bundle) != null) {
+            sourceMaps.unregister(bundle);
             version.incrementAndGet();
             logger.info("Unregistered bundle {} from GraalVM engine", bundle.getSymbolicName());
         }
     }
 
+    /** Maps positions in module bundles back to the sources they were built from. */
+    public SourceMaps getSourceMaps() {
+        return sourceMaps;
+    }
+
     @Activate
     public void activate(BundleContext bundleContext, Map<String, ?> props) {
         logger.info("Registering GraalVMEngine");
diff --git a/javascript-modules-engine-java/src/main/java/org/jahia/modules/javascript/modules/engine/jsengine/SourceMaps.java b/javascript-modules-engine-java/src/main/java/org/jahia/modules/javascript/modules/engine/jsengine/SourceMaps.java
new file mode 100644
index 00000000..b88851c1
--- /dev/null
+++ b/javascript-modules-engine-java/src/main/java/org/jahia/modules/javascript/modules/engine/jsengine/SourceMaps.java
@@ -0,0 +1,270 @@
+/*
+ * Copyright (C) 2002-2023 Jahia Solutions Group SA. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.jahia.modules.javascript.modules.engine.jsengine;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.osgi.framework.Bundle;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/**
+ * Maps positions in a module's bundled server script back to the sources it was built from, so that
+ * stack traces name the file a developer wrote rather than a line number in {@code index.js}.
+ *
+ * <p>Modules ship a standard <a href="https://tc39.es/ecma426/">source map</a> next to their server
+ * bundle (the Vite plugin emits it by default). Maps are parsed on first use and dropped when the
+ * module is unregistered.
+ */
+public class SourceMaps {
+
+    private static final Logger logger = LoggerFactory.getLogger(SourceMaps.class);
+
+    /**
+     * A frame as GraalVM reports it, e.g. {@code my-module/dist/server/index.js:1234} or
+     * {@code …index.js:1234:5}. The script name is the Graal source name, built by
+     * {@link GraalVMEngine} as {@code <bundle>/<script>}.
+     */
+    private static final Pattern FRAME = Pattern.compile("([\\w.-]+)/(\\S+?\\.js):(\\d+)(?::(\\d+))?");
+
+    /** Base64 alphabet used by the VLQ encoding of source map mappings. */
+    private static final String BASE64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+    /** One mapping: a column in a generated line, and where it comes from. */
+    private static final class Segment {
+        private final int generatedColumn;
+        private final String source;
+        private final int sourceLine;
+
+        private Segment(int generatedColumn, String source, int sourceLine) {
+            this.generatedColumn = generatedColumn;
+            this.source = source;
+            this.sourceLine = sourceLine;
+        }
+    }
+
+    /** Resolves a generated position to {@code <source>:<line>}; the seam unit tests replace. */
+    @FunctionalInterface
+    public interface PositionResolver {
+        Optional<String> resolve(String bundleSymbolicName, String script, int line, Integer column);
+    }
+
+    /** A parsed source map: segments per generated line (0-based). */
+    static final class ParsedMap {
+        private final List<List<Segment>> lines;
+
+        private ParsedMap(List<List<Segment>> lines) {
+            this.lines = lines;
+        }
+
+        Optional<String> lookup(int generatedLine, Integer generatedColumn) {
+            int index = generatedLine - 1;
+            if (index < 0 || index >= lines.size()) {
+                return Optional.empty();
+            }
+            List<Segment> segments = lines.get(index);
+            if (segments.isEmpty()) {
+                return Optional.empty();
+            }
+            // Without a column, or before the first mapping, the line's first mapping is the best guess
+            Segment best = segments.get(0);
+            if (generatedColumn != null) {
+                for (Segment segment : segments) {
+                    if (segment.generatedColumn > generatedColumn) {
+                        break;
+                    }
+                    best = segment;
+                }
+            }
+            return Optional.of(best.source + ":" + best.sourceLine);
+        }
+    }
+
+    /** Parsed maps, keyed by Graal source name ({@code <bundle>/<script>}). Absent value = no usable map. */
+    private final Map<String, Optional<ParsedMap>> maps = Collections.synchronizedMap(new HashMap<>());
+
+    /** Script paths per bundle, so unregistering a module drops its maps. */
+    private final Map<String, List<String>> scriptsByBundle = Collections.synchronizedMap(new HashMap<>());
+
+    private final Map<String, Bundle> bundles = Collections.synchronizedMap(new HashMap<>());
+
+    /** Tracks a module whose stack frames may need mapping. */
+    public void register(Bundle bundle, String script) {
+        bundles.put(bundle.getSymbolicName(), bundle);
+        scriptsByBundle.computeIfAbsent(bundle.getSymbolicName(), key -> new ArrayList<>()).add(script);
+    }
+
+    /** Forgets a module's maps, so a redeployed module is read again. */
+    public void unregister(Bundle bundle) {
+        String symbolicName = bundle.getSymbolicName();
+        bundles.remove(symbolicName);
+        List<String> scripts = scriptsByBundle.remove(symbolicName);
+        if (scripts != null) {
+            scripts.forEach(script -> maps.remove(symbolicName + "/" + script));
+        }
+    }
+
+    /**
+     * Rewrites every JavaScript frame of a stack trace to point at original sources, leaving anything
+     * it cannot map untouched.
+     *
+     * @param stackTrace a stack trace (or any text) possibly containing generated-position frames
+     * @return the same text with mapped positions substituted
+     */
+    public String rewrite(String stackTrace) {
+        return rewrite(stackTrace, this::map);
+    }
+
+    /** Same as {@link #rewrite(String)}, against an explicit resolver. */
+    public static String rewrite(String stackTrace, PositionResolver resolver) {
+        if (stackTrace == null) {
+            return null;
+        }
+        Matcher matcher = FRAME.matcher(stackTrace);
+        StringBuffer result = new StringBuffer();
+        while (matcher.find()) {
+            String bundle = matcher.group(1);
+            String script = matcher.group(2);
+            Integer column = matcher.group(4) == null ? null : Integer.valueOf(matcher.group(4));
+            String mapped = resolver.resolve(bundle, script, Integer.parseInt(matcher.group(3)), column)
+                    .map(position -> bundle + "/" + position)
+                    .orElseGet(matcher::group);
+            matcher.appendReplacement(result, Matcher.quoteReplacement(mapped));
+        }
+        matcher.appendTail(result);
+        return result.toString();
+    }
+
+    /**
+     * Resolves one generated position.
+     *
+     * @return {@code <source>:<line>}, or empty when no map covers that position
+     */
+    public Optional<String> map(String bundleSymbolicName, String script, int line, Integer column) {
+        return maps.computeIfAbsent(bundleSymbolicName + "/" + script,
+                        key -> parse(bundleSymbolicName, script))
+                .flatMap(parsed -> parsed.lookup(line, column));
+    }
+
+    private Optional<ParsedMap> parse(String bundleSymbolicName, String script) {
+        Bundle bundle = bundles.get(bundleSymbolicName);
+        if (bundle == null) {
+            return Optional.empty();
+        }
+        String content = GraalVMEngine.loadResource(bundle, script + ".map");
+        if (content == null) {
+            logger.debug("No source map next to {}/{}, stack traces will point at the bundle", bundleSymbolicName,
+                    script);
+            return Optional.empty();
+        }
+        try {
+            return Optional.of(parseMap(content));
+        } catch (Exception e) {
+            logger.warn("Ignoring unreadable source map for {}/{}", bundleSymbolicName, script, e);
+            return Optional.empty();
+        }
+    }
+
+    /** Parses a source map document. */
+    static ParsedMap parseMap(String json) {
+        try {
+            return parseMappings(new ObjectMapper().readTree(json));
+        } catch (Exception e) {
+            throw new IllegalArgumentException("Unreadable source map", e);
+        }
+    }
+
+    private static ParsedMap parseMappings(JsonNode map) {
+        String sourceRoot = map.path("sourceRoot").asText("");
+        List<String> sources = new ArrayList<>();
+        for (JsonNode source : map.path("sources")) {
+            sources.add(normalize(sourceRoot + source.asText()));
+        }
+
+        List<List<Segment>> lines = new ArrayList<>();
+        int sourceIndex = 0;
+        int sourceLine = 0;
+        for (String group : map.path("mappings").asText("").split(";", -1)) {
+            List<Segment> segments = new ArrayList<>();
+            int generatedColumn = 0;
+            for (String segment : group.split(",")) {
+                if (segment.isEmpty()) {
+                    continue;
+                }
+                int[] fields = decodeVlq(segment);
+                // A single field only moves the generated column: no source position to record
+                generatedColumn += fields[0];
+                if (fields.length < 4) {
+                    continue;
+                }
+                sourceIndex += fields[1];
+                sourceLine += fields[2];
+                if (sourceIndex >= 0 && sourceIndex < sources.size()) {
+                    // Source maps count lines from 0, stack traces from 1
+                    segments.add(new Segment(generatedColumn, sources.get(sourceIndex), sourceLine + 1));
+                }
+            }
+            lines.add(segments);
+        }
+        return new ParsedMap(lines);
+    }
+
+    /** Turns a build-relative source path into something recognisable in a module's own tree. */
+    private static String normalize(String source) {
+        String normalized = source;
+        while (normalized.startsWith("../")) {
+            normalized = normalized.substring(3);
+        }
+        return normalized.startsWith("./") ? normalized.substring(2) : normalized;
+    }
+
+    /** Decodes one comma-separated segment: a list of Base64 VLQ-encoded, zigzag-signed deltas. */
+    private static int[] decodeVlq(String segment) {
+        List<Integer> values = new ArrayList<>(5);
+        int value = 0;
+        int shift = 0;
+        for (int i = 0; i < segment.length(); i++) {
+            int digit = BASE64.indexOf(segment.charAt(i));
+            if (digit < 0) {
+                throw new IllegalArgumentException("Invalid VLQ character: " + segment.charAt(i));
+            }
+            boolean hasContinuation = (digit & 32) != 0;
+            value += (digit & 31) << shift;
+            if (hasContinuation) {
+                shift += 5;
+            } else {
+                // Least significant bit carries the sign
+                values.add((value & 1) == 1 ? -(value >>> 1) : value >>> 1);
+                value = 0;
+                shift = 0;
+            }
+        }
+        int[] fields = new int[values.size()];
+        for (int i = 0; i < fields.length; i++) {
+            fields[i] = values.get(i);
+        }
+        return fields;
+    }
+}
diff --git a/javascript-modules-engine-java/src/main/java/org/jahia/modules/javascript/modules/engine/views/JSScript.java b/javascript-modules-engine-java/src/main/java/org/jahia/modules/javascript/modules/engine/views/JSScript.java
index 8c79c04e..30fe9e2a 100644
--- a/javascript-modules-engine-java/src/main/java/org/jahia/modules/javascript/modules/engine/views/JSScript.java
+++ b/javascript-modules-engine-java/src/main/java/org/jahia/modules/javascript/modules/engine/views/JSScript.java
@@ -42,6 +42,22 @@ public JSScript(JSView jsView, GraalVMEngine graalVMEngine) {
 
     @Override
     public String execute(Resource resource, RenderContext renderContext) throws RenderException {
+        try {
+            return render(resource, renderContext);
+        } catch (RuntimeException | RenderException e) {
+            // Jahia's render chain replaces a failed fragment with an HTML comment and logs the raw
+            // exception, whose JS frames point inside the module's bundle. Log mapped positions, and
+            // in development make the failure visible on the page rather than only in the logs.
+            logger.error("Error rendering view {}:\n{}", jsView.getRegistryKey(),
+                    ViewRenderError.stackTrace(e, graalVMEngine.getSourceMaps()));
+            if (ViewRenderError.isDevelopmentMode()) {
+                return ViewRenderError.render(jsView.getRegistryKey(), e, graalVMEngine.getSourceMaps());
+            }
+            throw e;
+        }
+    }
+
+    private String render(Resource resource, RenderContext renderContext) throws RenderException {
         String output = graalVMEngine.doWithContext(ThrowingFunction.unchecked(contextProvider -> {
             Map<String, Object> viewValues = jsView.getRegistryInstance(contextProvider);
 
diff --git a/javascript-modules-engine-java/src/main/java/org/jahia/modules/javascript/modules/engine/views/ViewRenderError.java b/javascript-modules-engine-java/src/main/java/org/jahia/modules/javascript/modules/engine/views/ViewRenderError.java
new file mode 100644
index 00000000..c9d5fd80
--- /dev/null
+++ b/javascript-modules-engine-java/src/main/java/org/jahia/modules/javascript/modules/engine/views/ViewRenderError.java
@@ -0,0 +1,85 @@
+/*
+ * Copyright (C) 2002-2023 Jahia Solutions Group SA. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.jahia.modules.javascript.modules.engine.views;
+
+import org.jahia.modules.javascript.modules.engine.jsengine.SourceMaps;
+import org.jahia.settings.SettingsBean;
+
+import java.io.PrintWriter;
+import java.io.StringWriter;
+
+/**
+ * Turns a failed view render into something a developer can act on.
+ *
+ * <p>In production a failing view is swallowed by Jahia's render chain, which replaces the fragment
+ * with an HTML comment — the page stays up, which is what a live site wants. In development that
+ * silence hides the failure entirely, so the fragment is replaced by a visible box carrying the
+ * message and the stack trace, with positions mapped back to the module's own sources.
+ */
+public final class ViewRenderError {
+
+    private ViewRenderError() {
+    }
+
+    /** Whether failing views should render an error box instead of propagating the failure. */
+    public static boolean isDevelopmentMode() {
+        SettingsBean settings = SettingsBean.getInstance();
+        return settings != null && settings.isDevelopmentMode();
+    }
+
+    /**
+     * Renders the error as an HTML fragment.
+     *
+     * <p>Everything interpolated comes from module code, so it is HTML-escaped: an error message is
+     * not trusted markup.
+     */
+    public static String render(String viewKey, Throwable error, SourceMaps sourceMaps) {
+        return "<div style=\"margin:.5rem 0;padding:.75rem 1rem;border:2px solid #d33;border-radius:4px;"
+                + "background:#fff5f5;color:#900;font:13px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace\">"
+                + "<strong>Failed to render " + escape(viewKey) + "</strong>"
+                + "<div style=\"margin:.35rem 0;font-weight:bold\">" + escape(message(error))
+                + "</div><pre style=\"margin:0;white-space:pre-wrap;overflow-x:auto\">"
+                + escape(stackTrace(error, sourceMaps)) + "</pre>"
+                + "<div style=\"margin-top:.35rem;opacity:.7\">This box is only rendered in development mode.</div>"
+                + "</div>";
+    }
+
+    /** Escapes text coming from module code: an error message is data, not markup. */
+    private static String escape(String text) {
+        return text.replace("&", "&amp;")
+                .replace("<", "&lt;")
+                .replace(">", "&gt;")
+                .replace("\"", "&quot;")
+                .replace("'", "&#39;");
+    }
+
+    /** The message of the innermost cause, which is the one the module author wrote. */
+    public static String message(Throwable error) {
+        Throwable root = error;
+        while (root.getCause() != null && root.getCause() != root) {
+            root = root.getCause();
+        }
+        String message = root.getMessage();
+        return message != null ? message : root.toString();
+    }
+
+    /** The full stack trace, with generated positions mapped back to module sources. */
+    public static String stackTrace(Throwable error, SourceMaps sourceMaps) {
+        StringWriter writer = new StringWriter();
+        error.printStackTrace(new PrintWriter(writer));
+        return sourceMaps.rewrite(writer.toString());
+    }
+}
diff --git a/javascript-modules-engine-java/src/test/java/org/jahia/modules/javascript/modules/engine/jsengine/SourceMapsTest.java b/javascript-modules-engine-java/src/test/java/org/jahia/modules/javascript/modules/engine/jsengine/SourceMapsTest.java
new file mode 100644
index 00000000..dfabfc88
--- /dev/null
+++ b/javascript-modules-engine-java/src/test/java/org/jahia/modules/javascript/modules/engine/jsengine/SourceMapsTest.java
@@ -0,0 +1,110 @@
+/*
+ * Copyright (C) 2002-2023 Jahia Solutions Group SA. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.jahia.modules.javascript.modules.engine.jsengine;
+
+import org.junit.Test;
+
+import java.util.Optional;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+
+public class SourceMapsTest {
+
+    /**
+     * A source map as a bundler emits one, holding three mappings:
+     *
+     * <ul>
+     *   <li>generated 1:0 → {@code src/components/Blog/default.server.tsx} line 10
+     *   <li>generated 1:20 → the same file, line 41
+     *   <li>generated 3:0 → {@code src/lib/helper.ts} line 6
+     * </ul>
+     *
+     * Generated line 2 is deliberately left without any mapping.
+     */
+    private static final String MAP = "{\n"
+            + "  \"version\": 3,\n"
+            + "  \"file\": \"index.js\",\n"
+            + "  \"sources\": [\n"
+            + "    \"../../src/components/Blog/default.server.tsx\",\n"
+            + "    \"../../src/lib/helper.ts\"\n"
+            + "  ],\n"
+            + "  \"names\": [],\n"
+            + "  \"mappings\": \"AASA,oBA+BE;;ACnCA\"\n"
+            + "}";
+
+    @Test
+    public void GIVEN_a_mapped_position_WHEN_looking_it_up_THEN_the_original_source_and_line_are_returned() {
+        assertEquals(Optional.of("src/components/Blog/default.server.tsx:10"),
+                SourceMaps.parseMap(MAP).lookup(1, 0));
+    }
+
+    @Test
+    public void GIVEN_a_column_past_a_mapping_WHEN_looking_it_up_THEN_the_nearest_earlier_mapping_wins() {
+        assertEquals(Optional.of("src/components/Blog/default.server.tsx:41"),
+                SourceMaps.parseMap(MAP).lookup(1, 25));
+    }
+
+    @Test
+    public void GIVEN_no_column_WHEN_looking_up_a_line_THEN_its_first_mapping_is_used() {
+        assertEquals(Optional.of("src/components/Blog/default.server.tsx:10"),
+                SourceMaps.parseMap(MAP).lookup(1, null));
+    }
+
+    @Test
+    public void GIVEN_a_later_line_WHEN_looking_it_up_THEN_source_and_line_deltas_are_accumulated() {
+        assertEquals(Optional.of("src/lib/helper.ts:6"), SourceMaps.parseMap(MAP).lookup(3, 0));
+    }
+
+    @Test
+    public void GIVEN_a_line_without_mapping_WHEN_looking_it_up_THEN_nothing_is_returned() {
+        assertFalse(SourceMaps.parseMap(MAP).lookup(2, 0).isPresent());
+    }
+
+    @Test
+    public void GIVEN_a_line_outside_the_map_WHEN_looking_it_up_THEN_nothing_is_returned() {
+        assertFalse(SourceMaps.parseMap(MAP).lookup(9999, 0).isPresent());
+    }
+
+    @Test
+    public void GIVEN_a_stack_trace_WHEN_rewriting_it_THEN_mapped_frames_point_at_module_sources() {
+        String stackTrace = "org.graalvm.polyglot.PolyglotException: Error: boom\n"
+                + "\tat <js>.render(my-module/dist/server/index.js:3937)\n"
+                + "\tat <js>.:=>(my-module/dist/server/index.js:118:12)\n"
+                + "\tat org.jahia.services.render.RenderService.render(RenderService.java:182)\n";
+
+        String rewritten = SourceMaps.rewrite(stackTrace,
+                (bundle, script, line, column) -> Optional.of("src/components/Blog/default.server.tsx:" + line));
+
+        assertEquals("org.graalvm.polyglot.PolyglotException: Error: boom\n"
+                + "\tat <js>.render(my-module/src/components/Blog/default.server.tsx:3937)\n"
+                + "\tat <js>.:=>(my-module/src/components/Blog/default.server.tsx:118)\n"
+                // Java frames are left alone
+                + "\tat org.jahia.services.render.RenderService.render(RenderService.java:182)\n", rewritten);
+    }
+
+    @Test
+    public void GIVEN_a_frame_without_a_map_WHEN_rewriting_it_THEN_it_is_left_untouched() {
+        String stackTrace = "\tat <js>.render(my-module/dist/server/index.js:3937)\n";
+        assertEquals(stackTrace, SourceMaps.rewrite(stackTrace,
+                (bundle, script, line, column) -> Optional.empty()));
+    }
+
+    @Test
+    public void GIVEN_an_unregistered_bundle_WHEN_mapping_a_position_THEN_nothing_is_returned() {
+        assertFalse(new SourceMaps().map("never-registered", "dist/server/index.js", 1, 0).isPresent());
+    }
+}

From d1cf7b4f170cea7a50ef6dae760b77b4c1ac3835 Mon Sep 17 00:00:00 2001
From: Romain Gauthier <contact@romain.pm>
Date: Sat, 25 Jul 2026 10:28:17 +0200
Subject: [PATCH 2/2] docs(engine): correct how the render chain handles a
 failed view
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The class comment claimed production swallows a failing view into an HTML
comment while development stays silent. It is the other way around, and
neither half was quite right: AbstractFilter#getContentForError emits the
comment in both modes — with the message in development, with a timestamp
pointing at the logs in production — and a failure landing higher in the
render chain propagates as a server error instead. No behaviour change.
---
 .../javascript/modules/engine/views/JSScript.java  |  7 ++++---
 .../modules/engine/views/ViewRenderError.java      | 14 ++++++++++----
 2 files changed, 14 insertions(+), 7 deletions(-)

diff --git a/javascript-modules-engine-java/src/main/java/org/jahia/modules/javascript/modules/engine/views/JSScript.java b/javascript-modules-engine-java/src/main/java/org/jahia/modules/javascript/modules/engine/views/JSScript.java
index 30fe9e2a..5aae4e5a 100644
--- a/javascript-modules-engine-java/src/main/java/org/jahia/modules/javascript/modules/engine/views/JSScript.java
+++ b/javascript-modules-engine-java/src/main/java/org/jahia/modules/javascript/modules/engine/views/JSScript.java
@@ -45,9 +45,10 @@ public String execute(Resource resource, RenderContext renderContext) throws Ren
         try {
             return render(resource, renderContext);
         } catch (RuntimeException | RenderException e) {
-            // Jahia's render chain replaces a failed fragment with an HTML comment and logs the raw
-            // exception, whose JS frames point inside the module's bundle. Log mapped positions, and
-            // in development make the failure visible on the page rather than only in the logs.
+            // Whatever the render chain does with the failure — swallow it into an HTML comment or
+            // propagate it — the exception it logs has JS frames pointing inside the module's
+            // bundle. Log mapped positions instead, and in development mode make the failure
+            // visible on the page rather than leaving it to the logs and the page source.
             logger.error("Error rendering view {}:\n{}", jsView.getRegistryKey(),
                     ViewRenderError.stackTrace(e, graalVMEngine.getSourceMaps()));
             if (ViewRenderError.isDevelopmentMode()) {
diff --git a/javascript-modules-engine-java/src/main/java/org/jahia/modules/javascript/modules/engine/views/ViewRenderError.java b/javascript-modules-engine-java/src/main/java/org/jahia/modules/javascript/modules/engine/views/ViewRenderError.java
index c9d5fd80..75cb23fa 100644
--- a/javascript-modules-engine-java/src/main/java/org/jahia/modules/javascript/modules/engine/views/ViewRenderError.java
+++ b/javascript-modules-engine-java/src/main/java/org/jahia/modules/javascript/modules/engine/views/ViewRenderError.java
@@ -24,10 +24,16 @@
 /**
  * Turns a failed view render into something a developer can act on.
  *
- * <p>In production a failing view is swallowed by Jahia's render chain, which replaces the fragment
- * with an HTML comment — the page stays up, which is what a live site wants. In development that
- * silence hides the failure entirely, so the fragment is replaced by a visible box carrying the
- * message and the stack trace, with positions mapped back to the module's own sources.
+ * <p>A failing view leaves nothing useful on the page. Depending on where the failure lands in the
+ * render chain it either propagates as a server error, or is swallowed into an HTML comment by
+ * {@code AbstractFilter#getContentForError} — carrying the message in development mode, and only a
+ * timestamp pointing at the logs in production. The message a developer needs is therefore either
+ * absent from the page or hidden in its source, and the stack that reaches the logs points inside
+ * the module's bundle.
+ *
+ * <p>In development mode the fragment is replaced instead by a visible box carrying the message and
+ * the stack trace, with positions mapped back to the module's own sources. Production rendering is
+ * left untouched: what failed there before still fails the same way.
  */
 public final class ViewRenderError {