Preserve literal bindings inside passive code fences (#1055)

Author: taras

packages/cli/src/documents/sidekick/bindings.md

@@ -26,6 +26,11 @@ Sidekick responses, and the root bindings a REPL entry inherits.
   execute JavaScript and does not re-parse the result as XMD; interpolating an
   object is not JSON serialization. Write `\{` for a literal brace. Inline
   backticks do not prevent interpolation.
+- Passive fenced source preserves its tags, references and escaped braces even
+  when the response or entry has already bound the same names. Capture it with
+  `<Let as="code" select="code">` for later execution; use a longer outer fence
+  when that source contains fences of its own. Read `<Guide.Entries />` for the
+  complete authoring pattern.
 - Bindings created inside a component body or an `Each` iteration do not escape
   to later siblings. Use that construct's documented return or capture.
 - An entry inherits the JSON state earlier entries published, so a value an

packages/cli/src/documents/sidekick/entries.md

@@ -22,7 +22,9 @@ Sidekick responses that write an entry, and the REPL entry program they write.
   does not.
 - A fenced block with no `exec` or `eval` modifier is passive text, including
   its tags and braces. The language label alone does not make a fence
-  executable, and executable fences are unavailable in a response.
+  executable. References inside it stay literal even when your response or an
+  entry already bound the same names. Executable fences are unavailable in a
+  response.
 - Capture passive source with `<Let as="code" select="code">`, then pass the
   captured string to `<REPL.EntryInput>`. That fills the shared draft and runs
   none of it.
@@ -39,6 +41,7 @@ Sidekick responses that write an entry, and the REPL entry program they write.
 ## Example
 
 ````xmd
+<Let as="names" value={["response-only"]} />
 <Let as="code" select="code">
 ```xmd
 <Let as="names" value={["Ada", "Lin"]} />
@@ -53,11 +56,29 @@ Hello, {name}!
 ````
 
 The shared draft now holds that program as literal source and nothing has run.
-The `names` binding belongs to the future entry; `code` belongs to this
-response. `select="code"` extracts the first matching fenced block without its
+The response's `names` does not replace `{names}` in the fenced source. The
+entry binds its own `names` when run; `code` belongs to this response.
+`select="code"` extracts the first matching fenced block without its
 fence, and trims trailing whitespace — pass a direct string value when exact
 string boundaries matter.
 
+Use a longer outer fence when the saved entry contains an executable block:
+
+`````xmd
+<Let as="code" select="code">
+````xmd
+<Let as="message" value="hello" />
+```sh exec
+printf '%s\n' {message}
+```
+````
+</Let>
+<REPL.EntryInput>{code}</REPL.EntryInput>
+`````
+
+This fills the draft with the Let and exec block as source. Explicit submission
+runs that entry, where `{message}` resolves to `hello`.
+
 ### Create and use a session component across responses
 
 Read `<Guide.Environment />`, `<Guide.Entries />`, `<REPL.Environment />` and

packages/core/src/expand.ts

@@ -149,7 +149,7 @@ import { SourceOwner } from "./source-owner.ts";
 import { SchemaValidationError, validateProps, validateReturnValue } from "./validate.ts";
 import { isJsonObject, parseJson } from "./json.ts";
 import { healSegment } from "./heal.ts";
-import { scanSegments } from "./scanner.ts";
+import { scanSegments, splitTextFences } from "./scanner.ts";
 import { declareChildAnswers, expandAnswers, strayAnswerError } from "./answers.ts";
 import { DeclarationScan } from "./declaration-scan.ts";
 import { RESERVED_STRUCTURAL } from "./structural.ts";
@@ -995,23 +995,27 @@ function* expandListSegments(
         // Heal incomplete markdown constructs at segment boundaries (spec §2.3)
         // Runs synchronously — no yield, no journal entry
         const healed = healSegment(segment.content);
-        const protectedEscapes = healed.replaceAll("\\{", ESCAPED_BRACE_PLACEHOLDER);
         const textEvalEnv = yield* env;
         const textProps =
           textEvalEnv !== undefined && "props" in textEvalEnv.values
             ? textEvalEnv.values.props
             : parentProps;
-        // Interpolate {meta.key} and {props.key} — runtime, no journal
-        const interpolated = interpolate(protectedEscapes, parentMeta, textProps);
-        // Interpolate bare {name} refs from eval bindings (spec §6.4/§6.6).
-        // Runs after meta/props interpolation so component contract takes
-        // precedence. Only runs when a binding environment is in scope.
-        const final = textEvalEnv
-          ? interpolateEvalBindings(interpolated, textEvalEnv.values)
-          : interpolated;
+        const final = splitTextFences(segment, healed)
+          .map(({ content, passive }) => {
+            if (passive) {
+              return content;
+            }
+            const protectedEscapes = content.replaceAll("\\{", ESCAPED_BRACE_PLACEHOLDER);
+            const interpolated = interpolate(protectedEscapes, parentMeta, textProps);
+            const bound = textEvalEnv
+              ? interpolateEvalBindings(interpolated, textEvalEnv.values)
+              : interpolated;
+            return bound.replaceAll(ESCAPED_BRACE_PLACEHOLDER, "{");
+          })
+          .join("");
         result.push({
           type: "text",
-          content: final.replaceAll(ESCAPED_BRACE_PLACEHOLDER, "{"),
+          content: final,
         });
         break;
       }

packages/core/src/generated-interpolation.ts

@@ -23,11 +23,19 @@
  * whether it will change when evaluated is exactly its question.
  */
 
+import { splitTextFences } from "./scanner.ts";
+import type { TextSegment } from "./types.ts";
+
 const ESCAPED_BRACE_PLACEHOLDER = "";
 const FRONTMATTER_REFERENCE = /\{(meta|props)\.[^}]+\}/;
 const BINDING_REFERENCE = /\{[a-zA-Z_$][a-zA-Z0-9_$]*(?:\.[a-zA-Z_$][a-zA-Z0-9_$]*)*\}/;
 
-export function readsBinding(content: string): boolean {
-  const protectedEscapes = content.replaceAll("\\{", ESCAPED_BRACE_PLACEHOLDER);
-  return FRONTMATTER_REFERENCE.test(protectedEscapes) || BINDING_REFERENCE.test(protectedEscapes);
+export function readsBinding(segment: TextSegment): boolean {
+  return splitTextFences(segment).some((slice) => {
+    if (slice.passive) {
+      return false;
+    }
+    const protectedEscapes = slice.content.replaceAll("\\{", ESCAPED_BRACE_PLACEHOLDER);
+    return FRONTMATTER_REFERENCE.test(protectedEscapes) || BINDING_REFERENCE.test(protectedEscapes);
+  });
 }

packages/core/src/generated-xmd-preview.ts

@@ -49,7 +49,7 @@ import type { Result } from "effection";
 
 import { readsBinding } from "./generated-interpolation.ts";
 import { outputPropsViolation, validateBodyStructure } from "./body-structure.ts";
-import { scanSegments } from "./scanner.ts";
+import { scanSegments, splitTextFences } from "./scanner.ts";
 import type { UnfinishedConstruct } from "./scanner.ts";
 import type { ComponentElement, Segment } from "./types.ts";
 
@@ -161,8 +161,34 @@ function unfinishedRegion(
   }
   // The same walk again over the content delivered so far, so what counts as a
   // nested tag, a fence or an inline code span is decided once.
-  const content = source.slice(pending.contentStart);
-  return { output: literal(scanSegments(settledTail(content))) };
+  const content = source.slice(
+    0,
+    pending.contentStart + settledTail(source.slice(pending.contentStart)).length,
+  );
+  const unfinished: UnfinishedConstruct[] = [];
+  const segments = scanSegments(
+    content,
+    undefined,
+    undefined,
+    undefined,
+    unfinished,
+    pending.contentStart,
+  );
+  const first = earliest(unfinished);
+  return {
+    output: literal(
+      first === undefined
+        ? segments
+        : scanSegments(
+            content.slice(0, first.start),
+            undefined,
+            undefined,
+            undefined,
+            undefined,
+            pending.contentStart,
+          ),
+    ),
+  };
 }
 
 /**
@@ -228,8 +254,13 @@ function regions(segments: readonly Segment[]): { element: ComponentElement }[]
 function literal(segments: readonly Segment[]): string {
   let text = "";
   for (const segment of segments) {
-    if (segment.type === "text" && !readsBinding(segment.content)) {
-      text += segment.content;
+    if (segment.type === "text") {
+      text += readsBinding(segment)
+        ? splitTextFences(segment)
+            .filter((slice) => slice.passive)
+            .map((slice) => slice.content)
+            .join("")
+        : segment.content;
     }
   }
   return text;

packages/core/src/generated-xmd.ts

@@ -140,6 +140,7 @@ import { GeneratedDataExpressions, validateDataExpression } from "./generated-ex
 import { capturedBinding } from "./invocation-rules.ts";
 import { renderSegments } from "./render.ts";
 import { scanSegments } from "./scanner.ts";
+import { readsBinding } from "./generated-interpolation.ts";
 import { SourceOwner, sourceOwnerDescription } from "./source-owner.ts";
 import { RESERVED_STRUCTURAL } from "./structural.ts";
 // The ordinary source rules, read rather than reimplemented: a construct means
@@ -1350,25 +1351,6 @@ function admitted(entries: readonly Entry[]): Map<string, Entry[]> {
   return table;
 }
 
-/**
- * Whether this text would read anything.
- *
- * The two interpolation passes a text segment goes through are definitive
- * on what a reference is, so this asks them rather than guessing: `\{` is
- * protected exactly as expansion protects it, and what remains is matched by
- * the same shapes `interpolate()` and `interpolateEvalBindings()` consume.
- * Braces that neither pass would read — prose, a JSON sample, a CSS rule — are
- * left alone.
- */
-const ESCAPED_BRACE_PLACEHOLDER = "\uE000";
-const FRONTMATTER_REFERENCE = /\{(meta|props)\.[^}]+\}/;
-const BINDING_REFERENCE = /\{[a-zA-Z_$][a-zA-Z0-9_$]*(?:\.[a-zA-Z_$][a-zA-Z0-9_$]*)*\}/;
-
-function reads(content: string): boolean {
-  const protectedEscapes = content.replaceAll("\\{", ESCAPED_BRACE_PLACEHOLDER);
-  return FRONTMATTER_REFERENCE.test(protectedEscapes) || BINDING_REFERENCE.test(protectedEscapes);
-}
-
 /** Two lists of the same strings, in the same order. */
 function sameStrings(one: readonly string[], other: readonly string[]): boolean {
   return one.length === other.length && one.every((value, index) => value === other[index]);
@@ -1671,7 +1653,7 @@ function* walk(
         // own `<Let>` capture — and with it the one way a response has of
         // writing an entry draft, whose source is entry text that legitimately
         // carries braces of its own.
-        if (lexical.language !== "root" && reads(segment.content)) {
+        if (lexical.language !== "root" && readsBinding(segment)) {
           throw new Refusal("interpolation");
         }
         break;