feat: wrap copydeck placeholders in HTML at render time

Wrap copydeck placeholders in semantic HTML spans at render time

Placeholder values (name, loc, codeLine) are now HTML-escaped and
wrapped in typed spans (pfem__var, pfem__line/pfem__file, pfem__code)
when building the HTML output. Removes all inline styling / <i> tags.

Author: grega

copydecks/en/copydeck.json

@@ -23,8 +23,8 @@
             "not_message": ["is not defined"]
           },
           "title": "This variable doesn't exist yet",
-          "summary": "Your code uses the variable \"{{name}}\", but it hasn't been created yet. Check {{loc}}. If you meant to print the text <i>{{name}}</i>, put it in double quotes.",
-          "why": "Without speech marks Python treats <i>{{name}}</i> as a variable, and this variable does not exist yet.",
+          "summary": "Your code uses the variable {{name}}, but it hasn't been created yet. Check {{loc}}. If you meant to print the text {{name}}, put it in double quotes.",
+          "why": "Without speech marks Python treats {{name}} as a variable, and this variable does not exist yet.",
           "steps": [
             "If it is meant to be text, put speech marks around {{name}}.",
             "If it is meant to be a variable, make it first (for example: {{name}} = 0).",
@@ -36,7 +36,7 @@
             "match_message": ["is not defined"]
           },
           "title": "This variable doesn't exist here",
-          "summary": "\"{{name}}\" might be created somewhere else, but you're using it at {{loc}}. If you meant the text <i>{{name}}</i>, put it in double quotes.",
+          "summary": "{{name}} might be created somewhere else, but you're using it at {{loc}}. If you meant the text {{name}}, put it in double quotes.",
           "why": "A variable created in another place might not be available here.",
           "steps": [
             "Move the line that makes it to above where you use it.",
@@ -50,7 +50,7 @@
       "variants": [
         {
           "title": "Variable used before it gets a value in this part of the code",
-          "summary": "Here, \"{{name}}\" is used at {{loc}} before you give it a value.",
+          "summary": "Here, {{name}} is used at {{loc}} before you give it a value.",
           "why": "You have used the variable before it has been given a value. If used within a subroutine, the variable must either be global and given a value outside the subroutine definition, or local and given a value inside the subroutine, before it is used. ",
           "steps": [
             "Give it a value first (add a line like {{name}} = ... before you use it)."

src/engine.ts

@@ -70,15 +70,32 @@ const pickVariant = (trace: Trace, code: string | undefined) => {
     codeLine: codeLine
   };
 
+  const linePart = trace.line ? `<span class="pfem__line">${escapeHtml(lineStr)} ${escapeHtml(String(trace.line))}</span>` : null;
+  const filePart = trace.file ? `<span class="pfem__file">${escapeHtml(trace.file)}</span>` : null;
+  const htmlLoc =
+    linePart && filePart ? `${linePart} ${escapeHtml(inStr)} ${filePart}` :
+    linePart ?? filePart ?? escapeHtml(thisFileStr);
+
+  const htmlTransforms: Record<string, (v: string) => string> = {
+    name:     (v) => `<span class="pfem__var">${escapeHtml(v)}</span>`,
+    loc:      (_) => htmlLoc,
+    codeLine: (v) => `<span class="pfem__code">${escapeHtml(v)}</span>`,
+  };
+
   for (let i = 0; i < entry.variants.length; i++) {
     const v = entry.variants[i];
     if (!matches(v)) continue;
 
-    const title = tmpl(v.title, vars);
+    const title   = tmpl(v.title,   vars);
     const summary = tmpl(v.summary, vars);
-    const why = v.why ? tmpl(v.why, vars) : undefined;
-    const steps = v.steps?.map((s) => tmpl(s, vars));
-    const badges = v.badges;
+    const why     = v.why ? tmpl(v.why, vars) : undefined;
+    const steps   = v.steps?.map((s) => tmpl(s, vars));
+    const badges  = v.badges;
+
+    const titleHtml   = tmpl(v.title,   vars, htmlTransforms);
+    const summaryHtml = tmpl(v.summary, vars, htmlTransforms);
+    const whyHtml     = v.why ? tmpl(v.why, vars, htmlTransforms) : undefined;
+    const stepsHtml   = v.steps?.map((s) => tmpl(s, vars, htmlTransforms));
 
     let patch: string | undefined = undefined;
     if (trace.type === "AttributeError" && /\.push\s*\(/i.test(codeLine)) {
@@ -95,10 +112,10 @@ const pickVariant = (trace: Trace, code: string | undefined) => {
     }
 
     const html = [
-      `<div class="pfem__title">${escapeHtml(title)}</div>`,
-      `<div class="pfem__summary">${summary}</div>`,
-      why ? `<div class="pfem__why">${why}</div>` : "",
-      steps?.length ? `<ul class="pfem__steps">${steps.map((s) => `<li>${s}</li>`).join("")}</ul>` : "",
+      `<div class="pfem__title">${titleHtml}</div>`,
+      `<div class="pfem__summary">${summaryHtml}</div>`,
+      whyHtml ? `<div class="pfem__why">${whyHtml}</div>` : "",
+      stepsHtml?.length ? `<ul class="pfem__steps">${stepsHtml.map((s) => `<li>${s}</li>`).join("")}</ul>` : "",
       patch ? `<pre class="pfem__patch">${escapeHtml(patch)}</pre>` : "",
       `<details class="pfem__details"><summary>${escapeHtml(getUiString("originalError", "Original error"))}</summary><pre>${escapeHtml(
         (trace.type || getUiString("error", "Error")) + ": " + trace.message

src/utils.ts

@@ -1,8 +1,16 @@
 export const escapeHtml = (s: string) =>
   s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]!));
 
-export const tmpl = (s: string, vars: Record<string, string>) =>
-  (s || "").replace(/\{\{\s*([a-zA-Z0-9_]+)\s*\}\}/g, (_, k) => (k in vars ? String(vars[k]) : ""));
+export const tmpl = (
+  s: string,
+  vars: Record<string, string>,
+  transforms?: Record<string, (v: string) => string>
+) =>
+  (s || "").replace(/\{\{\s*([a-zA-Z0-9_]+)\s*\}\}/g, (_, k) => {
+    if (!(k in vars)) return "";
+    const v = String(vars[k]);
+    return transforms?.[k] ? transforms[k](v) : v;
+  });
 
 export const safeRegexTest = (pattern: string, input: string) => {
   try {

tests/engine.test.ts

@@ -107,4 +107,44 @@ AttributeError: 'list' object has no attribute 'push'`;
     expect(res.trace.type).toBe("AttributeError");
     expect(res.patch).toContain(".append(");
   });
+
+  it("plain result fields contain no HTML tags", () => {
+    const code = `print("Hello")\nprint(kittens)\n`;
+    const raw = `Traceback (most recent call last):
+  File "main.py", line 2, in <module>
+NameError: name 'kittens' is not defined`;
+    const res = friendlyExplain({ error: raw, code, runtime: "skulpt" });
+    expect(res.summary).not.toMatch(/<[^>]+>/);
+    expect(res.why).not.toMatch(/<[^>]+>/);
+    res.steps?.forEach((s) => expect(s).not.toMatch(/<[^>]+>/));
+  });
+
+  it("html output wraps {{name}} in pfem__var span", () => {
+    const code = `print("Hello")\nprint(kittens)\n`;
+    const raw = `Traceback (most recent call last):
+  File "main.py", line 2, in <module>
+NameError: name 'kittens' is not defined`;
+    const res = friendlyExplain({ error: raw, code, runtime: "skulpt" });
+    expect(res.html).toContain('<span class="pfem__var">kittens</span>');
+  });
+
+  it("html output wraps {{loc}} line and file in separate spans", () => {
+    const code = `print("Hello")\nprint(kittens)\n`;
+    const raw = `Traceback (most recent call last):
+  File "main.py", line 2, in <module>
+NameError: name 'kittens' is not defined`;
+    const res = friendlyExplain({ error: raw, code, runtime: "skulpt" });
+    expect(res.html).toContain('<span class="pfem__line">');
+    expect(res.html).toContain('<span class="pfem__file">main.py</span>');
+  });
+
+  it("escapes HTML in codeLine within html output", () => {
+    const code = `for i in range(3)<script>alert(1)</script>\n  print(i)`;
+    const raw = `Traceback (most recent call last):
+  File "main.py", line 1
+SyntaxError: invalid syntax`;
+    const res = friendlyExplain({ error: raw, code, runtime: "skulpt" });
+    expect(res.html).not.toContain("<script>");
+    expect(res.html).toContain("&lt;script&gt;");
+  });
 });