@zvndev/darkmown 2.6.1-next.11.g82bb8d7 → 2.7.0

package/src/compiler/markdown.js

@@ -7,16 +7,23 @@
 
 import MarkdownIt from "markdown-it";
 import { highlightCode } from "../highlight.js";
-import { LOOP_META, recordRead, wdError } from "./context.js";
+import { LOOP_META, lineOf, recordRead, wdError } from "./context.js";
 import { applyPipeline, fmtAttr, validatePipes } from "./format.js";
 import {
   escapeHtml,
   getPath,
+  interpolateBound,
   interpolateLeaf,
   lookupVar,
-  resolveStateKey
+  resolveStateKey,
+  unsafeUrlValue
 } from "./interpolation.js";
 
+// The two halves of the destination contract, re-exported together: a caller
+// painting an href itself (a loop row's build-time initial) has to encode the
+// value the same way this module does and answer the same scheme question.
+export { unsafeUrlValue };
+
 /**
  * @typedef {import("./context.js").Meta} Meta
  * @typedef {import("./context.js").Ctx} Ctx
@@ -29,6 +36,8 @@ import {
 const md = new MarkdownIt({ html: false, highlight: highlightCode });
 md.use(bindingPlugin);
 md.use(attrsPlugin);
+md.use(attrBindPlugin);
+md.use(rawHtmlPlugin);
 md.use(anchorPlugin);
 
 // Raw HTML in markdown is escaped by default: a stray `<script>` or `onerror=`
@@ -50,63 +59,413 @@ export function selectMd(meta) {
     mdRawHtml = new MarkdownIt({ html: true, highlight: highlightCode });
     mdRawHtml.use(bindingPlugin);
     mdRawHtml.use(attrsPlugin);
+    mdRawHtml.use(attrBindPlugin);
+    mdRawHtml.use(rawHtmlPlugin);
     mdRawHtml.use(anchorPlugin);
   }
   return mdRawHtml;
 }
 
 /**
+ * Render one prose chunk.
  * @param {string} text
  * @param {Ctx} ctx
+ * @param {number} [index] 0-based line index the chunk starts at in the current
+ *   `compileBody` slice, so a warning about a binding inside it reports the true
+ *   `file:line`. Defaults to the top of the slice.
  * @returns {string}
  */
-export function renderProse(text, ctx) {
-  text = resolveDestinationBindings(text, ctx);
-  return (ctx.md ?? md).render(text, {
-    resolveBinding: (/** @type {string} */ expr) => resolveBindingHtml(expr, ctx),
+export function renderProse(text, ctx, index = 0) {
+  /** @type {PendingAttr[]} */
+  const attrs = [];
+  text = resolveDestinationBindings(text, ctx, attrs, index);
+  const html = (ctx.md ?? md).render(text, {
+    resolveBinding: (/** @type {string} */ expr) => resolveBinding(expr, ctx),
+    // Raw-HTML interpolation needs the compile context AND the chunk's offset,
+    // and markdown-it's env is the only channel into a core rule. `attrs` is the
+    // destination-binding registry `attrBindPlugin` reads back (see below).
+    wd: { ctx, index, attrs },
     headingSlugs: ctx.comp.headingSlugs
   });
+  if (!attrs.length) return html;
+  // A `](…)` that markdown did NOT turn into a link — the commonest being an
+  // inline code span documenting the syntax — keeps its placeholder. Put the
+  // author's own braces back rather than shipping the marker.
+  return html.replace(ATTR_MARK_RE, (mark, n) =>
+    attrs[Number(n)] ? escapeHtml(attrs[Number(n)].raw) : mark
+  );
+}
+
+// ---------------------------------------------------------------------------
+// THE SILENT-FAILURE CLASS: interpolation that markdown never sees.
+//
+// `{ name }` is an INLINE rule, so it only fires where markdown-it is parsing
+// inline content. Three positions are not inline content, and in all three the
+// framework used to emit the author's braces verbatim with no error and no
+// warning:
+//
+//   1. A link/image destination. `[a]({ x })` worked (one special case), but
+//      `[a](/p/{ x }/)` did not: `{ … }` contains spaces, a markdown destination
+//      may not, so the link never forms and the WHOLE construct degrades to the
+//      literal text `[a](/p/value/)`.
+//   2. An attribute inside raw HTML (`<a href="{ x }">`, `html: true`). The tag
+//      is one opaque `html_inline` token; nothing inside it is ever parsed.
+//   3. The body of a raw `html_block` (`<div>{ x }</div>`).
+//
+// Every build-time value resolves in all three. A REACTIVE value in a
+// destination now BINDS: the destination pass plants a placeholder, and
+// `attrBindPlugin` turns the assembled href/src into a `data-wd-attr` template
+// the runtime repaints (see there). Raw HTML still cannot bind — a tag is one
+// opaque token with no element to mark — so that position keeps the warning.
+// ---------------------------------------------------------------------------
+
+/**
+ * Warn (non-fatal) that a reactive value landed in raw HTML, which has no
+ * element for the runtime to mark.
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index of the offending line in the slice.
+ * @param {string} expr The binding source text, without braces.
+ * @param {boolean} painted Whether the initial value was written into the output.
+ * @returns {void}
+ */
+function warnUnbindable(ctx, index, expr, painted) {
+  const outcome = painted
+    ? "its build-time value is painted once and then never updates"
+    : "it stays literal text";
+  ctx.comp.warnings.push(
+    `${ctx.file}:${lineOf(ctx, index)}: "{ ${expr} }" is reactive, but raw HTML (an attribute or an html block) cannot bind, so ${outcome}. ` +
+      `Move the value into ordinary text or a markdown link/image destination (where { ${expr} } does bind), or update it from a colocated .js with wd.subscribe.`
+  );
+}
+
+// ---------------------------------------------------------------------------
+// REACTIVE ATTRIBUTE BINDING (a link/image destination).
+//
+// A destination is not inline content, so there is no token for the inline rule
+// to emit and nothing to hang `data-wd-bind` on. The pass below therefore runs
+// in two halves:
+//
+//   1. `resolveDestinationBindings` (pre-parse) substitutes a build-time value
+//      directly, exactly as before, and replaces a REACTIVE one with the
+//      placeholder `~wd-attr-<n>~`, recording what it stands for. The
+//      placeholder is deliberately shaped out of characters markdown-it's URL
+//      normalizer leaves untouched, so it survives into the token's href/src.
+//   2. `attrBindPlugin` (core rule) finds the placeholder in the assembled
+//      href/src, splits the value into literal chunks + bindings, writes the
+//      initial paint, and stamps the template onto the element.
+//
+// The template rides on `data-wd-attr` (state/`:computed`, repainted in the
+// runtime's text-bind pass) or `data-wd-each-attr` (anything per-row, filled by
+// `fillItem`) — the same split `data-wd-bind` / `data-wd-each` already use for
+// text. One template serves every row, so a per-row destination paints EMPTY at
+// build time and gets its first real value on hydrate.
+// ---------------------------------------------------------------------------
+
+/**
+ * One reactive binding found in a destination: the serialized template part the
+ * runtime evaluates, plus the build-time text to paint for it.
+ * @typedef {object} PendingAttr
+ * @property {["s", string, string] | ["i", string] | ["m", string]} part
+ *   `s` = state key + sub-path, `i` = loop-row sub-path, `m` = row meta variable.
+ * @property {string} text Build-time paint ("" for anything per-row).
+ * @property {string} raw The author's own `{ … }` source, restored when the
+ *   `](…)` turned out not to be a link after all.
+ */
+
+/** @param {number} n @returns {string} */
+const attrMark = (n) => `~wd-attr-${n}~`;
+const ATTR_MARK_RE = /~wd-attr-(\d+)~/g;
+
+// A value going into a markdown link destination is URL text, not markdown, and
+// the destination has no quoting: an unencoded `)` CLOSES it and hands whatever
+// follows back to the parser (raw HTML on an `html: true` page), and a space
+// silently kills the link. Encode the ASCII characters that carry meaning there
+// by hand, because encodeURIComponent deliberately leaves `(`, `)` and `'`
+// alone. Non-ASCII is left to markdown-it's own normalizeLink.
+// biome-ignore lint/suspicious/noControlCharactersInRegex: intentional — a control character in a destination has to be encoded, not passed through.
+const DEST_UNSAFE = /[\u0000-\u0020()<>"'`\\\u007F]/g;
+
+/**
+ * `unknown` rather than `string`: a caller painting a row's own initial href
+ * holds whatever `getPath` returned, and the coercion is right here.
+ * @param {unknown} value
+ * @returns {string}
+ */
+export const encodeDest = (value) =>
+  String(value).replace(
+    DEST_UNSAFE,
+    (c) => `%${c.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}`
+  );
+
+/**
+ * Byte ranges of the inline code spans on one line, so a destination being SHOWN
+ * rather than used stays literal. `` `[x](/p/{ p.slug }/)` `` in a docs
+ * paragraph documents the syntax, exactly like the fenced-block skip.
+ * @param {string} line
+ * @returns {[number, number][]}
+ */
+function codeSpansOf(line) {
+  /** @type {[number, number][]} */
+  const spans = [];
+  const runs = [...line.matchAll(/`+/g)];
+  for (let i = 0; i < runs.length; i++) {
+    for (let j = i + 1; j < runs.length; j++) {
+      // CommonMark closes a run of N backticks with a run of exactly N.
+      if (runs[j][0].length !== runs[i][0].length) continue;
+      spans.push([runs[i].index, runs[j].index + runs[j][0].length]);
+      i = j;
+      break;
+    }
+  }
+  return spans;
 }
 
 /**
  * Pre-resolve `{ expr }` interpolations sitting in a markdown link/image
  * destination — the `](…)` slot — so a build-time `@loop` (or any static scope)
- * can drive an href/src. A markdown destination cannot contain the spaces inside
- * `{ … }`, so markdown-it would otherwise never form the link; substituting the
- * static value here lets the normal link/image parser run. Only build-time
- * (static-scope) values are substituted — reactive `:state`/reactive-loop
- * bindings resolve to `null` and are left untouched (they cannot live in a
- * destination). Issue #19.
+ * can drive an href/src, and a reactive value can be bound by the core rule.
+ *
+ * A markdown destination cannot contain the spaces inside `{ … }`, so markdown-it
+ * would never form the link; substituting here first lets the normal link/image
+ * parser run. Every `{ … }` in the destination is substituted, not just one at
+ * the very start — `/products/{ p.slug }/` is the shape a collection listing
+ * actually writes.
+ *
+ * Fenced code is skipped: a docs page showing `[{ p.name }](/p/{ p.slug }/)`
+ * inside a ```` ```wd ```` block is DOCUMENTING the syntax, not using it.
  * @param {string} text
  * @param {Ctx} ctx
+ * @param {PendingAttr[]} attrs Registry the core rule reads placeholders back from.
+ * @param {number} index 0-based line index of the slice, for `file:line`.
  * @returns {string}
  */
-function resolveDestinationBindings(text, ctx) {
-  return text.replace(
-    /(\]\(\s*)\{\s*([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)\s*\}/g,
-    (whole, prefix, expr) => {
-      const raw = resolveBindingRaw(expr, ctx);
-      return raw == null ? whole : prefix + raw;
+function resolveDestinationBindings(text, ctx, attrs, index) {
+  const lines = text.split("\n");
+  /** @type {string | null} */
+  let fence = null;
+  for (let i = 0; i < lines.length; i++) {
+    const fenceMatch = lines[i].match(/^(```+|~~~+)/);
+    if (fence) {
+      if (fenceMatch && fenceMatch[1][0] === fence[0] && fenceMatch[1].length >= fence.length)
+        fence = null;
+      continue;
     }
-  );
+    if (fenceMatch) {
+      fence = fenceMatch[1];
+      continue;
+    }
+    const spans = codeSpansOf(lines[i]);
+    lines[i] = lines[i].replace(/\]\(([^)\n]*)\)/g, (whole, dest, offset) => {
+      if (spans.some(([a, b]) => offset >= a && offset < b)) return whole;
+      const filled = dest.replace(
+        /\{\s*([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)\s*\}/g,
+        (/** @type {string} */ brace, /** @type {string} */ expr) => {
+          const found = resolveBinding(expr, ctx);
+          if (!found) return brace; // not in scope — leave the author's text alone
+          if (found.kind === "static") {
+            // The scheme test runs on the RAW value, before encoding, because
+            // that is the string the runtime's guard sees. Encoding first would
+            // turn " javascript:x" into "%20javascript:x" and quietly ship it.
+            if (unsafeUrlValue(found.text)) {
+              warnUnsafeUrl(ctx, index + i, expr);
+              return "";
+            }
+            return encodeDest(found.text);
+          }
+          const part = /** @type {PendingAttr["part"]} */ (
+            found.kind === "state"
+              ? ["s", found.key ?? "", found.path ?? ""]
+              : found.meta
+                ? ["m", found.meta]
+                : ["i", found.path ?? ""]
+          );
+          attrs.push({ part, text: found.text, raw: brace });
+          return attrMark(attrs.length - 1);
+        }
+      );
+      return filled === dest ? whole : `](${filled})`;
+    });
+  }
+  return lines.join("\n");
 }
 
 /**
- * Resolve `{ expr }` to its raw static value (a plain string) for use in a
- * destination, or `null` when the binding is reactive or not in build-time
- * scope. Mirrors the static branch of {@link resolveBindingHtml} but returns the
- * unescaped value (markdown-it normalizes the URL).
+ * markdown-it plugin (core rule): turn a destination placeholder back into a
+ * bound attribute. Reads the `~wd-attr-<n>~` markers out of a `link_open`'s
+ * `href` / an `image`'s `src`, writes the build-time paint, and stamps the
+ * template the runtime re-evaluates on every render.
+ *
+ * The build-time paint runs through the same scheme guard the runtime uses, on
+ * the same unencoded string: markdown-it's own `validateLink` vetted the
+ * placeholder, not the value that replaced it, so an unsafe seed would
+ * otherwise ship in the HTML.
+ * @param {MarkdownIt} mdInstance
+ * @returns {void}
+ */
+function attrBindPlugin(mdInstance) {
+  mdInstance.core.ruler.push("wd_attr_bind", (state) => {
+    /** @type {PendingAttr[] | undefined} */
+    const registry = state.env?.wd?.attrs;
+    if (!registry || !registry.length) return false;
+    for (const block of state.tokens) {
+      for (const token of block.children ?? []) {
+        const name = token.type === "link_open" ? "href" : token.type === "image" ? "src" : "";
+        if (!name) continue;
+        const raw = token.attrGet(name);
+        if (!raw || !raw.includes("~wd-attr-")) continue;
+        /** @type {(string | PendingAttr)[]} */
+        const template = [];
+        let initial = "";
+        let plain = ""; // the same value UNencoded: what the runtime will hold
+        let perRow = false;
+        let end = 0;
+        ATTR_MARK_RE.lastIndex = 0;
+        /** @type {RegExpExecArray | null} */
+        let hit;
+        while ((hit = ATTR_MARK_RE.exec(raw))) {
+          const pending = registry[Number(hit[1])];
+          if (!pending) continue; // not one of ours — leave the author's text
+          if (hit.index > end) {
+            template.push(raw.slice(end, hit.index));
+            initial += raw.slice(end, hit.index);
+            plain += raw.slice(end, hit.index);
+          }
+          template.push(pending);
+          initial += encodeDest(pending.text);
+          plain += pending.text;
+          if (pending.part[0] !== "s") perRow = true;
+          end = hit.index + hit[0].length;
+        }
+        if (!template.length) continue;
+        if (end < raw.length) {
+          template.push(raw.slice(end));
+          initial += raw.slice(end);
+          plain += raw.slice(end);
+        }
+        // Tested on the UNencoded assembly, exactly as `applyAttr` will test it
+        // in the browser: encoding first hides a leading space or control
+        // character from a guard that is meant to strip it.
+        token.attrSet(name, unsafeUrlValue(plain) ? "" : initial);
+        token.attrSet(
+          perRow ? "data-wd-each-attr" : "data-wd-attr",
+          JSON.stringify([name, ...template.map((t) => (typeof t === "string" ? t : t.part))])
+        );
+      }
+    }
+    return false;
+  });
+}
+
+/**
+ * markdown-it plugin (core rule): resolve `{ expr }` inside RAW HTML — the
+ * opaque `html_inline` tokens a tag becomes and the `html_block` tokens a
+ * block-level element becomes, both of which only exist on an `html: true` page.
+ * Values are HTML-escaped, which is correct in both positions a brace can sit
+ * in (an attribute value and element text), so no tag-position analysis is
+ * needed.
+ *
+ * `.md` files never reach this: `compileFile` renders them with no
+ * `resolveBinding` in the env, and this rule is a no-op without it — the
+ * extension stays the feature gate.
+ * @param {MarkdownIt} mdInstance
+ * @returns {void}
+ */
+function rawHtmlPlugin(mdInstance) {
+  mdInstance.core.ruler.push("wd_raw_html", (state) => {
+    const wd = state.env?.wd;
+    if (!wd) return false;
+    for (const block of state.tokens) {
+      const line = wd.index + (block.map ? block.map[0] : 0);
+      if (block.type === "html_block") {
+        block.content = fillRawHtml(block.content, wd.ctx, line);
+        continue;
+      }
+      // Inline children carry no line map, so count the line breaks walked past:
+      // one softbreak/hardbreak per source newline inside the block. Keeps the
+      // warning on the author's actual line, not the top of the paragraph.
+      let offset = 0;
+      for (const child of block.children ?? []) {
+        if (child.type === "softbreak" || child.type === "hardbreak") offset++;
+        // `child.meta.wdText` marks a token THIS layer already produced (a
+        // resolved binding). Its content is DATA, not template: without the skip,
+        // a state value that happens to read `{ meta.title }` would be resolved a
+        // second time and leak whatever `title` holds into the page.
+        else if (child.type === "html_inline" && child.meta?.wdText === undefined)
+          child.content = fillRawHtml(child.content, wd.ctx, line + offset);
+      }
+    }
+    return false;
+  });
+}
+
+// The value of a URL-bearing attribute, as far as a fragment has been written.
+// The capture is the value SO FAR: `<a href="java` yields "java", so the guard
+// can test what the attribute will actually hold rather than what one brace
+// happened to resolve to. Escaping is no defense here: `href` and friends
+// resolve `javascript:` without any quote breakout, and unlike a markdown
+// destination nothing upstream vets an author's own raw `<a href="…">`.
+const URL_ATTR_TAIL =
+  /\b(?:href|src|action|formaction|xlink:href)\s*=\s*(?:"([^"]*)|'([^']*)|([^\s>"']*))$/i;
+
+/**
+ * Warn that a value in URL position carries a scheme the browser would execute.
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index, for `file:line`.
  * @param {string} expr
+ * @returns {void}
+ */
+function warnUnsafeUrl(ctx, index, expr) {
+  ctx.comp.warnings.push(
+    `${ctx.file}:${lineOf(ctx, index)}: "{ ${expr} }" resolves to a javascript:, data: or vbscript: URL, so the attribute is emitted empty. ` +
+      `Use an https:, mailto: or site-relative value, or render it as text rather than a link target.`
+  );
+}
+
+/**
+ * Substitute every `{ expr }` in a raw-HTML fragment with its escaped value.
+ *
+ * The output is assembled by hand rather than through `String.replace` because
+ * the URL guard has to see the attribute value BEING BUILT: `<a href="java{ x }">`
+ * with x = "script:alert(1)" is a live javascript: URL that no single brace
+ * value would ever look unsafe on its own. When the assembled value trips the
+ * guard, the literal head of that value is dropped from the output too, so the
+ * attribute lands empty instead of half-written.
+ * @param {string} html
  * @param {Ctx} ctx
- * @returns {string | null}
+ * @param {number} index 0-based line index of the fragment, for warnings.
+ * @returns {string}
  */
-function resolveBindingRaw(expr, ctx) {
-  const segs = expr.split(".");
-  const found = lookupVar(ctx.scope, segs[0]);
-  if (!found.found) return null;
-  const resolved = getPath(found.value, segs.slice(1));
-  const leaf = interpolateLeaf(resolved, expr, ctx);
-  return leaf == null ? null : String(leaf);
+function fillRawHtml(html, ctx, index) {
+  const brace = /\{\s*([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)\s*\}/g;
+  let out = "";
+  let last = 0;
+  /** @type {RegExpExecArray | null} */
+  let hit;
+  while ((hit = brace.exec(html))) {
+    out += html.slice(last, hit.index);
+    last = hit.index + hit[0].length;
+    const expr = hit[1];
+    const found = resolveBinding(expr, ctx);
+    if (!found) {
+      out += hit[0];
+      continue;
+    }
+    if (found.kind === "row") {
+      warnUnbindable(ctx, index, expr, false);
+      out += hit[0];
+      continue;
+    }
+    if (found.kind === "state") warnUnbindable(ctx, index, expr, true);
+    const open = URL_ATTR_TAIL.exec(out);
+    const head = open ? (open[1] ?? open[2] ?? open[3]) : "";
+    if (open && unsafeUrlValue(head + found.text)) {
+      warnUnsafeUrl(ctx, index, expr);
+      out = out.slice(0, out.length - head.length); // the head belongs to the refused value
+      continue;
+    }
+    out += escapeHtml(found.text);
+  }
+  return out + html.slice(last);
 }
 
 /**
@@ -126,11 +485,16 @@ function bindingPlugin(mdInstance) {
     );
     if (!match) return false;
     const resolve = state.env?.resolveBinding;
-    const html = resolve ? resolve(match[1].trim()) : null;
-    if (typeof html !== "string") return false;
+    const found = resolve ? resolve(match[1].trim()) : null;
+    if (!found) return false;
     if (!silent) {
       const token = state.push("html_inline", "", 0);
-      token.content = html;
+      token.content = found.html;
+      // The heading-anchor rule reads this back: an id must be a slug of what the
+      // reader SEES, and what the reader sees here is `found.text`, not the
+      // markup carrying it. Marking the token also keeps genuine author HTML
+      // (`## Hi <b>x</b>`) contributing nothing, exactly as before.
+      token.meta = { wdText: found.text };
     }
     state.pos += match[0].length;
     return true;
@@ -223,8 +587,9 @@ export function slugify(text) {
  * so long pages are linkable without any JS. Duplicate slugs dedupe with
  * `-1`/`-2` suffixes; the counters live in `env.headingSlugs` so a page whose
  * prose renders in chunks (directives between headings) still dedupes across
- * the whole document. Bindings and inline HTML inside a heading contribute no
- * slug text — only literal text and inline code do.
+ * the whole document. A `{ name }` binding contributes its resolved text (its
+ * initial value when reactive); author-written inline HTML still contributes
+ * none, so only text the reader actually reads shapes the id.
  * @param {MarkdownIt} mdInstance
  * @returns {void}
  */
@@ -237,6 +602,12 @@ function anchorPlugin(mdInstance) {
       let text = "";
       for (const child of tokens[i + 1].children ?? []) {
         if (child.type === "text" || child.type === "code_inline") text += child.content;
+        // A `{ name }` binding is real heading text — without it every
+        // interpolated heading on a site slugged to the same `section`,
+        // `section-1`, `section-2`, which is what darkmown.com/blog/ shipped.
+        // Reactive bindings contribute their INITIAL value: the id has to be
+        // stable and crawlable, so it is minted once at build time.
+        else if (child.meta?.wdText) text += child.meta.wdText;
       }
       const base = slugify(text);
       const seen = counts.get(base) ?? 0;
@@ -248,13 +619,32 @@ function anchorPlugin(mdInstance) {
 }
 
 /**
- * Resolve a `{ name.path }` binding to HTML: loop item span, static value, or
- * a reactive bind span. Returns null when nothing in scope matches.
+ * A resolved `{ name.path }` binding.
+ * @typedef {object} Binding
+ * @property {string} html What the inline rule emits: a `data-wd-each` /
+ *   `data-wd-bind` span for a reactive value, the escaped value for a static one.
+ * @property {string} text The PLAIN resolved text (unescaped, no markup) — a
+ *   reactive value's initial paint. This is what a link destination, a raw-HTML
+ *   attribute, and a heading slug need; `html` is unusable in all three.
+ * @property {"static" | "state" | "row"} kind Where the value came from, and
+ *   therefore what the non-inline positions may do with it: `static` is a
+ *   build-time value and always safe to substitute; `state` is `:state`/`:store`
+ *   and paints its seed then binds; `row` is a reactive `@loop` row, whose ONE
+ *   template serves every row, so it paints nothing and binds per row.
+ * @property {string} [key] For `state`: the fully-qualified state key.
+ * @property {string} [path] For `state`/`row`: the dotted sub-path under it ("" for the whole value).
+ * @property {string} [meta] For `row`: the per-row meta variable (`index`, `number`, …).
+ */
+
+/**
+ * Resolve a `{ name.path }` binding: loop item span, static value, or a reactive
+ * bind span. Returns null when nothing in scope matches, which every caller
+ * treats as "leave the author's braces exactly as written".
  * @param {string} expr
  * @param {Ctx} ctx
- * @returns {string | null}
+ * @returns {Binding | null}
  */
-function resolveBindingHtml(expr, ctx) {
+function resolveBinding(expr, ctx) {
   const { path, stages } = validatePipes(expr, ctx);
   const segs = path.split(".");
   const head = segs[0];
@@ -270,19 +660,32 @@ function resolveBindingHtml(expr, ctx) {
         `"{ ${expr} }" uses the loop meta variable "${head}" outside a @loop in ${ctx.file}. Move it into a loop body, or rename your value.`,
         { code: "WD005", file: ctx.file }
       );
-    if (ctx.loopItem) return `<span data-wd-each-meta="${LOOP_META[head]}"${fmt}></span>`; // reactive: filled per row
+    if (ctx.loopItem)
+      // reactive: filled per row, so there is no single build-time text.
+      return {
+        html: `<span data-wd-each-meta="${LOOP_META[head]}"${fmt}></span>`,
+        text: "",
+        kind: "row",
+        meta: LOOP_META[head]
+      };
     // static: the value is in scope (injected by staticUnroll); fall through.
   }
 
   if (ctx.loopItem && head === ctx.loopItem) {
     const rest = segs.slice(1).join(".");
-    return `<span data-wd-each${rest ? ` data-wd-path="${escapeHtml(rest)}"` : ""}${fmt}></span>`;
+    return {
+      html: `<span data-wd-each${rest ? ` data-wd-path="${escapeHtml(rest)}"` : ""}${fmt}></span>`,
+      text: "",
+      kind: "row",
+      path: rest
+    };
   }
 
   const staticValue = lookupVar(ctx.scope, head);
   if (staticValue.found) {
     const resolved = getPath(staticValue.value, segs.slice(1));
-    return escapeHtml(interpolateLeaf(fold(resolved), expr, ctx));
+    const text = interpolateLeaf(fold(resolved), expr, ctx);
+    return { html: escapeHtml(text), text, kind: "static" };
   }
 
   const key = resolveStateKey(head, ctx);
@@ -292,7 +695,17 @@ function resolveBindingHtml(expr, ctx) {
     const initial = getPath(ctx.comp.state.get(key), segs.slice(1));
     const rest = segs.slice(1).join(".");
     const pathAttr = rest ? ` data-wd-path="${escapeHtml(rest)}"` : "";
-    return `<span data-wd-bind="${key}"${pathAttr}${fmt}>${escapeHtml(interpolateLeaf(fold(initial), expr, ctx))}</span>`;
+    // interpolateBound, not interpolateLeaf: the runtime repaints this node with
+    // textContent, so the initial paint has to use the runtime's own coercion or
+    // an array bind silently changes from "a, b" to "a,b" on first render.
+    const text = interpolateBound(fold(initial), expr, ctx);
+    return {
+      html: `<span data-wd-bind="${escapeHtml(key)}"${pathAttr}${fmt}>${escapeHtml(text)}</span>`,
+      text,
+      kind: "state",
+      key,
+      path: rest
+    };
   }
 
   return null;

package/src/compiler/page.js

@@ -293,8 +293,11 @@ export function enhanceImages(html, paths, reader) {
     /** @type {string[]} */
     const add = [];
     // Dimensions only when the author hasn't sized it — adding one axis to a
-    // manually-sized image would distort its aspect ratio.
-    if (!has("width") && !has("height")) {
+    // manually-sized image would distort its aspect ratio. A REACTIVE src
+    // (`![alt]({ photo })`, marked `data-wd-attr`/`data-wd-each-attr`) is sized
+    // from whatever the seed happened to be, so baking width/height would
+    // stretch every later image to the first one's aspect ratio.
+    if (!has("width") && !has("height") && !/\bdata-wd-(?:each-)?attr\s*=/.test(tag)) {
       const dim = measureImage(srcOf(tag), paths, reader);
       if (dim) add.push(`width="${dim.width}"`, `height="${dim.height}"`);
     }
@@ -427,7 +430,9 @@ export function compileFile(
   const real = comp.reader.realpath(file);
   if (stack.includes(real)) {
     throw wdError(
-      `[WD612] Include cycle detected: ${[...stack, real].map((p) => path.basename(p)).join(" -> ")}`,
+      // No literal `[WD612]` here: wdError prefixes the code itself, and the
+      // hardcoded copy printed it twice (`[WD612] [WD612] Include cycle …`).
+      `Include cycle detected: ${[...stack, real].map((p) => path.basename(p)).join(" -> ")}`,
       { code: "WD612", file }
     );
   }