@caelo-cms/shared 0.10.72 → 0.11.1

package/src/css-var-aliases.test.ts

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import {
+  formatCssVarRenameReport,
+  renameCssVarAliases,
+  themeVarForAlias,
+} from "./css-var-aliases.js";
+import { scanCssVars } from "./css-var-scan.js";
+
+const THEME = [
+  "--color-background",
+  "--color-foreground",
+  "--color-muted",
+  "--color-muted-foreground",
+  "--color-border",
+  "--color-accent",
+];
+
+describe("renameCssVarAliases", () => {
+  // The header CSS of e2e-livedit run 40351690739.
+  const css =
+    ".site-header{border-bottom:1px solid var(--color-border, #e5e5e5);background:var(--color-surface, #fff);}\n" +
+    ".site-header__brand{color:var(--color-text, #111);}\n" +
+    ".site-header__panel{background:var(--color-surface, #fff);}\n" +
+    ".site-header__col h3{color:var(--color-text-muted,#888);}";
+
+  it("renames common role names to the theme's names, every occurrence", () => {
+    const r = renameCssVarAliases(css, THEME, new Set());
+    expect(r.css).not.toContain("--color-surface");
+    expect(r.css).not.toContain("var(--color-text,");
+    expect(r.css).toContain("background:var(--color-background, #fff)");
+    expect(r.css).toContain("color:var(--color-foreground, #111)");
+    expect(r.css).toContain("color:var(--color-muted-foreground,#888)");
+    expect(r.renames).toEqual([
+      { from: "--color-surface", to: "--color-background", count: 2 },
+      { from: "--color-text", to: "--color-foreground", count: 1 },
+      { from: "--color-text-muted", to: "--color-muted-foreground", count: 1 },
+    ]);
+    expect(formatCssVarRenameReport(r.renames)).toContain("--color-surface→--color-background×2");
+  });
+
+  it("leaves known names, the author's own properties and unmapped names alone", () => {
+    const own = ":root{--surface:#fafafa}.a{background:var(--surface);color:var(--brand-ink)}";
+    const r = renameCssVarAliases(own, THEME, new Set(["--surface"]));
+    expect(r.css).toBe(own);
+    expect(r.renames).toEqual([]);
+  });
+
+  it("renames only when the theme emits the target", () => {
+    expect(themeVarForAlias("--color-surface-raised", new Set(THEME))).toBeNull();
+    expect(themeVarForAlias("--text", new Set(THEME))).toBe("--color-foreground");
+  });
+});
+
+describe("scanCssVars suggestions", () => {
+  it("suggests the theme's role name, not the nearest spelling", () => {
+    const [u] = scanCssVars({ css: ".a{color:var(--color-text, #111)}", knownVars: THEME });
+    expect(u?.suggestion).toBe("--color-foreground");
+  });
+});

package/src/css-var-aliases.ts

@@ -0,0 +1,109 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Common names for theme roles, mapped to the names Caelo's theme emits.
+ *
+ * Module CSS is authored against conventions the model knows from other
+ * design systems: `--color-text`, `--color-surface`, `--color-text-muted`.
+ * Caelo's theme calls those roles `--color-foreground`, `--color-background`
+ * and `--color-muted-foreground`. The write-time scan used to answer with an
+ * edit-distance guess (`--color-text` → "did you mean `--color-accent`?"),
+ * so the AI loaded the theme and renamed every reference with edit_content
+ * — two to three extra tool calls per module, and a failed one when the
+ * same declaration appeared twice (e2e-livedit run 40351690739). A name
+ * that unambiguously means a role the theme has is renamed before the
+ * write instead, and the tool result says so, the same way theme-literal
+ * binding rewrites a literal that equals a token (issue #164). Only names
+ * in this table are touched, and only when the theme emits the target.
+ */
+
+/** Role name (without `--` and an optional `color-` prefix) → theme role. */
+const ROLE_ALIASES: Readonly<Record<string, string>> = {
+  text: "foreground",
+  "text-primary": "foreground",
+  "text-color": "foreground",
+  "body-text": "foreground",
+  fg: "foreground",
+  heading: "foreground",
+  "text-muted": "muted-foreground",
+  "text-secondary": "muted-foreground",
+  "text-subtle": "muted-foreground",
+  "muted-text": "muted-foreground",
+  "fg-muted": "muted-foreground",
+  surface: "background",
+  bg: "background",
+  "page-bg": "background",
+  "body-bg": "background",
+  "surface-muted": "muted",
+  "surface-alt": "muted",
+  "bg-muted": "muted",
+  "bg-subtle": "muted",
+  "surface-raised": "card",
+  "card-bg": "card",
+  "border-color": "border",
+  divider: "border",
+  line: "border",
+};
+
+/** The theme var an unknown name stands for, or null. */
+export function themeVarForAlias(name: string, knownVars: ReadonlySet<string>): string | null {
+  const bare = name.replace(/^--/, "").replace(/^color-/, "");
+  const role = ROLE_ALIASES[bare];
+  if (role === undefined) return null;
+  const target = `--color-${role}`;
+  return knownVars.has(target) ? target : null;
+}
+
+/** `var(` + the referenced name, when the name ends there. */
+const VAR_NAME_RE = /(var\(\s*)(--[a-zA-Z0-9_-]+)(?![a-zA-Z0-9_-])/g;
+
+/** One renamed reference. */
+export interface CssVarRename {
+  readonly from: string;
+  readonly to: string;
+  readonly count: number;
+}
+
+/**
+ * Rename `var(--alias…)` references to the theme's name for that role.
+ * A name the CSS itself defines (`--surface: …`) is the author's own
+ * property and stays.
+ */
+export function renameCssVarAliases(
+  css: string,
+  knownVars: readonly string[],
+  definedInCss: ReadonlySet<string>,
+): { css: string; renames: CssVarRename[] } {
+  const known = new Set(knownVars);
+  const targets = new Map<string, string>();
+  const counts = new Map<string, number>();
+  // One pass over the references, no pattern built from a name.
+  const out = css.replace(VAR_NAME_RE, (match, open: string, name: string) => {
+    if (known.has(name) || definedInCss.has(name)) return match;
+    let to = targets.get(name);
+    if (to === undefined) {
+      const resolved = themeVarForAlias(name, known);
+      if (resolved === null) return match;
+      to = resolved;
+      targets.set(name, to);
+    }
+    counts.set(name, (counts.get(name) ?? 0) + 1);
+    return `${open}${to}`;
+  });
+  const renames: CssVarRename[] = [...targets].map(([from, to]) => ({
+    from,
+    to,
+    count: counts.get(from) ?? 0,
+  }));
+  return { css: out, renames };
+}
+
+/** Tool-result sentence for the renames, or null. */
+export function formatCssVarRenameReport(renames: readonly CssVarRename[]): string | null {
+  if (renames.length === 0) return null;
+  return ` 🔗 renamed to the theme's names: ${renames
+    .map((r) => `${r.from}→${r.to}${r.count > 1 ? `×${r.count}` : ""}`)
+    .join(
+      ", ",
+    )} — the STORED css uses the theme's names, so anchor later edit_content calls on those.`;
+}

package/src/css-var-scan.ts

@@ -17,6 +17,8 @@
  * that is legitimate authoring, not drift.
  */
 
+import { themeVarForAlias } from "./css-var-aliases.js";
+
 /** One `var(--x)` reference found in CSS. */
 export interface CssVarReference {
   readonly name: string;
@@ -97,6 +99,13 @@ export function scanCssVars(input: CssVarScanInput): UnknownCssVar[] {
   for (const ref of extractCssVarReferences(input.css)) {
     if (known.has(ref.name) || reported.has(ref.name)) continue;
     reported.add(ref.name);
+    // A common role name (`--color-text`) suggests the theme's name for
+    // that role, not the nearest spelling (which was `--color-accent`).
+    const alias = themeVarForAlias(ref.name, known);
+    if (alias !== null) {
+      unknown.push({ name: ref.name, hasFallback: ref.hasFallback, suggestion: alias });
+      continue;
+    }
     let best: string | null = null;
     let bestDist = Number.POSITIVE_INFINITY;
     for (const candidate of known) {

package/src/edit-markers.test.ts

@@ -2,19 +2,38 @@
 
 import { describe, expect, it } from "bun:test";
 import { finalizeEditMarkers, wrapEditableValues } from "./edit-markers.js";
-import { renderTemplate } from "./template-engine.js";
+import { DEFAULT_LIST_TYPES } from "./lists/default-types.js";
+import { fixtureData } from "./lists/list-fixtures.test.js";
+import { createListRenderContext } from "./lists/resolve.js";
+import { renderTemplate, type TemplateField } from "./template-engine.js";
 
-const FIELDS = [
+const FIELDS: TemplateField[] = [
   { name: "title", kind: "text" },
-  { name: "tags", kind: "text-list" },
-  { name: "links", kind: "link-list" },
+  { name: "tags", kind: "list", listType: "texts" },
+  { name: "links", kind: "list", listType: "links" },
   { name: "photo", kind: "image" },
-] as const;
+];
+const listTypes = (slug: string) => DEFAULT_LIST_TYPES.find((t) => t.slug === slug);
+const lists = createListRenderContext(fixtureData()).forPage(null);
+
+const T1 = "00000000-0000-4000-9000-000000000001";
+const T2 = "00000000-0000-4000-9000-000000000002";
+const L1 = "00000000-0000-4000-9000-000000000003";
+const tags = (...t: string[]) =>
+  t.map((text, i) => ({ id: [T1, T2][i], node: "text", values: { text } }));
+const links = (label: string, href: string) => [
+  { id: L1, node: "link", values: { label, link: { href } } },
+];
+/** A marker path as the comment encodes it (`-` → %2D). */
+const enc = (p: string) => encodeURIComponent(p).replace(/-/g, "%2D");
 
 function render(html: string, values: Record<string, unknown>, sharedPages = 0): string {
-  const wrapped = wrapEditableValues(values, FIELDS);
-  const rendered = renderTemplate({ html, fields: [...FIELDS], contentValues: wrapped }).html;
-  return finalizeEditMarkers(rendered, "content#2", sharedPages);
+  const wrapped = wrapEditableValues(values, FIELDS, listTypes);
+  const rendered = renderTemplate({ html, fields: FIELDS, contentValues: wrapped, lists }).html;
+  return finalizeEditMarkers(rendered, "content#2", sharedPages).replace(
+    / data-caelo-list-item="[^"]*"/g,
+    "",
+  );
 }
 
 const marked = (fields: string, shared = 0) =>
@@ -34,17 +53,14 @@ describe("edit markers (#917)", () => {
     expect(render("<h1>{{title}}</h1>", { title: "Hi" }, 4)).toContain(open("title", 4));
   });
 
-  it("marks text-list items and link-list labels with their index", () => {
+  it("marks local list entries' text and link targets by entry id", () => {
     const html = render(
-      '<ul>{{#tags}}<li>{{.}}</li>{{/tags}}</ul><nav>{{#links}}<a href="{{href}}">{{label}}</a>{{/links}}</nav>',
-      {
-        tags: ["a", "b"],
-        links: [{ label: "Docs", href: "/docs" }],
-      },
+      '<ul>{{#tags}}<li>{{text}}</li>{{/tags}}</ul><nav>{{#links}}<a href="{{link}}">{{label}}</a>{{/links}}</nav>',
+      { tags: tags("a", "b"), links: links("Docs", "/docs") },
     );
-    expect(html).toContain(`<li>${open("tags.1")}b${close}</li>`);
+    expect(html).toContain(`<li>${open(enc(`tags.${T2}.text`))}b${close}</li>`);
     expect(html).toContain(
-      `<a href="/docs"${marked("href=links.0.href")}>${open("links.0.label")}Docs${close}</a>`,
+      `<a href="/docs"${marked(`href=${enc(`links.${L1}.link.href`)}`)}>${open(enc(`links.${L1}.label`))}Docs${close}</a>`,
     );
   });
 
@@ -61,12 +77,12 @@ describe("edit markers (#917)", () => {
 
   it("marks link targets, images and alt text on their tag (#918)", () => {
     const html = render(
-      '{{#links}}<a href="{{href}}">{{label}}</a>{{/links}}<img src="{{photo}}" alt="{{title}}"/>',
-      { links: [{ label: "Docs", href: "/docs" }], photo: "/m/cup.webp", title: "A cup" },
+      '{{#links}}<a href="{{link}}">{{label}}</a>{{/links}}<img src="{{photo}}" alt="{{title}}"/>',
+      { links: links("Docs", "/docs"), photo: "/m/cup.webp", title: "A cup" },
       2,
     );
     expect(html).toContain(
-      `<a href="/docs"${marked("href=links.0.href", 2)}>${open("links.0.label", 2)}Docs${close}</a>`,
+      `<a href="/docs"${marked(`href=${enc(`links.${L1}.link.href`)}`, 2)}>${open(enc(`links.${L1}.label`), 2)}Docs${close}</a>`,
     );
     expect(html).toContain(
       `<img src="/m/cup.webp" alt="A cup"${marked("src=photo alt=title", 2)}/>`,
@@ -80,9 +96,9 @@ describe("edit markers (#917)", () => {
   });
 
   it("does not mark values that carry markup, empty values, or non-text kinds", () => {
-    const html = render("<h1>{{title}}</h1><p>{{#tags}}{{.}}{{/tags}}</p>", {
+    const html = render("<h1>{{title}}</h1><p>{{#tags}}{{text}}{{/tags}}</p>", {
       title: "<b>Bold</b>",
-      tags: [" "],
+      tags: tags(" "),
     });
     expect(html).toBe("<h1><b>Bold</b></h1><p> </p>");
     expect(wrapEditableValues({ n: 3 }, [{ name: "n", kind: "number" }])).toEqual({ n: 3 });

package/src/edit-markers.ts

@@ -29,6 +29,8 @@
  * be edited as plain text without destroying that markup.
  */
 
+import type { ListTypeDef } from "./lists/list-type.js";
+
 const START = "\uE000";
 const SEP = "\uE001";
 const END = "\uE002";
@@ -38,21 +40,29 @@ const SENTINELS = /[\uE000-\uE002]/g;
 export const EDIT_MARKER_PREFIX = "caelo:f";
 
 /**
- * Field kinds the preview marks: text (`text`, `text-list` items,
- * `link-list` labels) and link / image targets (`url`, `image`,
- * `link-list` hrefs, #918) — the latter usually land in `href` / `src`.
+ * Field kinds the preview marks: text (`text`, the `text` fields of a
+ * local `list`'s entries) and link / image targets (`url`, `image`, the
+ * `href` of a local list entry's `link` fields, #918) — the latter
+ * usually land in `href` / `src`.
  */
-const EDITABLE_KINDS = new Set(["text", "text-list", "link-list", "url", "image"]);
+const EDITABLE_KINDS = new Set(["text", "url", "image", "list"]);
 
 /** Attributes whose marked value the editor can change (link target, image, alt text). */
 const MARKABLE_ATTRIBUTES = new Set(["href", "src", "alt"]);
 
-/** Field shape {@link wrapEditableValues} needs: name + kind. */
+/** Field shape {@link wrapEditableValues} needs: name + kind (+ a list field's type and binding). */
 export interface EditableFieldDef {
   readonly name: string;
   readonly kind?: string;
+  readonly listType?: string;
+  readonly bind?: string;
 }
 
+/** List type lookup by slug, for marking a local list's entries. */
+export type EditableListTypes = (slug: string) => ListTypeDef | undefined;
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
 function editable(value: unknown): value is string {
   return typeof value === "string" && value.trim().length > 0 && !value.includes("<");
 }
@@ -65,9 +75,12 @@ function wrap(path: string, value: string): string {
  * Wrap the editable text of a content instance's values in sentinels.
  * Returns a new object; non-editable values pass through untouched.
  *
- * Paths: `<field>` for a `text` / `url` / `image` field, `<field>.<i>`
- * for a `text-list` item, `<field>.<i>.label` / `<field>.<i>.href` for a
- * `link-list` item's label / target.
+ * Paths: `<field>` for a `text` / `url` / `image` field;
+ * `<field>.<itemId>.<key>` for a `text` value of a local list entry and
+ * `<field>.<itemId>.<key>.href` for the target of its `link` value (item
+ * ids are stable uuids, so a path survives reordering). Shared lists are
+ * edited in the list editor, not in place: their values are not part of
+ * the placement.
  *
  * @example
  * wrapEditableValues({ hero_title: "Hi" }, [{ name: "hero_title", kind: "text" }]);
@@ -76,6 +89,7 @@ function wrap(path: string, value: string): string {
 export function wrapEditableValues(
   values: Readonly<Record<string, unknown>>,
   fields: readonly EditableFieldDef[],
+  listTypes?: EditableListTypes,
 ): Record<string, unknown> {
   const out: Record<string, unknown> = { ...values };
   for (const f of fields) {
@@ -84,23 +98,41 @@ export function wrapEditableValues(
     const v = values[f.name];
     if (kind === "text" || kind === "url" || kind === "image") {
       if (editable(v)) out[f.name] = wrap(f.name, v);
-    } else if (kind === "text-list" && Array.isArray(v)) {
-      out[f.name] = v.map((item, i) => (editable(item) ? wrap(`${f.name}.${i}`, item) : item));
-    } else if (kind === "link-list" && Array.isArray(v)) {
-      out[f.name] = v.map((item, i) => {
-        if (typeof item !== "object" || item === null) return item;
-        const { label, href } = item as { label?: unknown; href?: unknown };
-        return {
-          ...item,
-          ...(editable(label) ? { label: wrap(`${f.name}.${i}.label`, label) } : {}),
-          ...(editable(href) ? { href: wrap(`${f.name}.${i}.href`, href) } : {}),
-        };
-      });
+    } else if (kind === "list" && (f.bind ?? "local") === "local" && Array.isArray(v)) {
+      const type = f.listType === undefined ? undefined : listTypes?.(f.listType);
+      if (type) out[f.name] = wrapListEntries(f.name, v, type);
     }
   }
   return out;
 }
 
+/** Mark the text and link targets of local list entries, at any depth. */
+function wrapListEntries(field: string, items: readonly unknown[], type: ListTypeDef): unknown[] {
+  return items.map((raw) => {
+    if (typeof raw !== "object" || raw === null) return raw;
+    const item = raw as { id?: unknown; node?: unknown; values?: unknown; children?: unknown };
+    const node = typeof item.node === "string" ? type.nodes[item.node] : undefined;
+    if (!node || typeof item.id !== "string" || !UUID_RE.test(item.id)) return raw;
+    const values = { ...((item.values ?? {}) as Record<string, unknown>) };
+    for (const def of node.fields) {
+      const v = values[def.name];
+      const at = `${field}.${item.id}.${def.name}`;
+      if (def.type === "text" && editable(v)) values[def.name] = wrap(at, v);
+      if (def.type === "link" && typeof v === "object" && v !== null) {
+        const href = (v as { href?: unknown }).href;
+        if (editable(href)) values[def.name] = { ...v, href: wrap(`${at}.href`, href) };
+      }
+    }
+    return {
+      ...item,
+      values,
+      ...(Array.isArray(item.children)
+        ? { children: wrapListEntries(field, item.children, type) }
+        : {}),
+    };
+  });
+}
+
 /** Comment-safe encoding: no `--`, no `>`, no whitespace. */
 function attr(value: string): string {
   return encodeURIComponent(value).replace(/-/g, "%2D");

package/src/escaped-line-breaks.ts

@@ -0,0 +1,221 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Source text whose line breaks arrived string-escaped as a whole.
+ *
+ * e2e-livedit run 40532297620 (release gate v0.11.1): `add_module`'s html,
+ * css and js came in with every line break as the two characters `\` `n`
+ * (`(function () {\n  document…`). Stored as sent, the footer showed `\n`
+ * text, its CSS broke, and the page's shared module `<script>` threw
+ * `SyntaxError: Invalid or unexpected token` — a backslash outside a string
+ * is not JavaScript. Like the other whole-value transport encodings
+ * (`source-text-transport.ts`) the AI tool boundary decodes it, once.
+ *
+ * The same two characters are legitimate inside a string literal (`"a\nb"`
+ * in JS or a CSS `content`), a regex, an HTML attribute value, or the body
+ * of a raw-text element. A value is only decoded when EVERY escaped line
+ * break sits where a real line break could have stood — between tokens of
+ * code, or in markup text between tags. One escape inside a literal makes
+ * the value ambiguous and it is left exactly as sent: decoding it would
+ * turn valid source into broken source (a raw newline inside a JS string
+ * is a syntax error). The op validators still refuse what is left broken
+ * (module js is parsed in admin-core `module-js-syntax.ts`).
+ */
+
+/** Which grammar a source value is written in; decides what counts as a literal. */
+export type SourceLanguage = "html" | "css" | "js";
+
+/** `\n` or `\r\n` escape starting at `i` (a single backslash, not an escaped one). */
+function escapedLineBreakLength(value: string, i: number): number {
+  if (value[i] !== "\\") return 0;
+  if (value[i + 1] === "n") return 2;
+  if (value[i + 1] === "r" && value[i + 2] === "\\" && value[i + 3] === "n") return 4;
+  return 0;
+}
+
+/** Characters after which a `/` in JS starts a regex literal rather than a division. */
+const REGEX_PRECEDERS = new Set([..."(,=:[!&|?{};+-*%<>~^"]);
+
+/**
+ * Index just past a quoted literal starting at `start` (its quote char), or
+ * -1 when an escaped line break sits inside it.
+ */
+function skipQuoted(value: string, start: number): number {
+  const quote = value[start];
+  let j = start + 1;
+  while (j < value.length) {
+    const ch = value[j];
+    if (ch === "\\") {
+      if (value[j + 1] === "n" || value[j + 1] === "r") return -1;
+      j += 2;
+      continue;
+    }
+    if (ch === quote) return j + 1;
+    j += 1;
+  }
+  return j;
+}
+
+/** True when an escaped line break sits inside a JS string, template, or regex literal. */
+function jsLiteralHoldsEscape(value: string): boolean {
+  let prev = "";
+  let i = 0;
+  while (i < value.length) {
+    const ch = value[i] as string;
+    const lineBreak = escapedLineBreakLength(value, i);
+    if (lineBreak > 0) {
+      prev = "";
+      i += lineBreak;
+      continue;
+    }
+    if (ch === "\\") {
+      i += 2;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      const end = skipQuoted(value, i);
+      if (end < 0) return true;
+      prev = ch;
+      i = end;
+      continue;
+    }
+    if (ch === "/" && value[i + 1] === "/") {
+      // A line comment runs to the next (escaped) line break.
+      i += 2;
+      while (i < value.length && escapedLineBreakLength(value, i) === 0) i += 1;
+      continue;
+    }
+    if (ch === "/" && value[i + 1] === "*") {
+      const close = value.indexOf("*/", i + 2);
+      i = close < 0 ? value.length : close + 2;
+      continue;
+    }
+    if (ch === "/" && (prev === "" || REGEX_PRECEDERS.has(prev))) {
+      let j = i + 1;
+      let inClass = false;
+      while (j < value.length) {
+        const r = value[j];
+        if (r === "\\") {
+          if (value[j + 1] === "n" || value[j + 1] === "r") return true;
+          j += 2;
+          continue;
+        }
+        if (r === "[") inClass = true;
+        else if (r === "]") inClass = false;
+        else if (r === "/" && !inClass) break;
+        j += 1;
+      }
+      prev = "/";
+      i = j + 1;
+      continue;
+    }
+    if (ch !== " " && ch !== "\t") prev = ch;
+    i += 1;
+  }
+  return false;
+}
+
+/** True when an escaped line break sits inside a CSS string. */
+function cssLiteralHoldsEscape(value: string): boolean {
+  let i = 0;
+  while (i < value.length) {
+    const ch = value[i];
+    if (ch === "/" && value[i + 1] === "*") {
+      const close = value.indexOf("*/", i + 2);
+      i = close < 0 ? value.length : close + 2;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      const end = skipQuoted(value, i);
+      if (end < 0) return true;
+      i = end;
+      continue;
+    }
+    i += ch === "\\" ? 2 : 1;
+  }
+  return false;
+}
+
+/** Elements whose body is not markup text: an escape there belongs to that body. */
+const RAW_TEXT_ELEMENTS = new Set(["script", "style", "pre", "textarea"]);
+
+/** True when an escaped line break sits inside an attribute value, a comment, or a raw-text element body. */
+function htmlLiteralHoldsEscape(value: string): boolean {
+  const lower = value.toLowerCase();
+  let i = 0;
+  while (i < value.length) {
+    if (value[i] !== "<") {
+      i += 1;
+      continue;
+    }
+    if (value.startsWith("<!--", i)) {
+      const close = value.indexOf("-->", i + 4);
+      const end = close < 0 ? value.length : close + 3;
+      if (/(?<!\\)\\[nr]/.test(value.slice(i, end))) return true;
+      i = end;
+      continue;
+    }
+    const name = /^<([a-zA-Z][a-zA-Z0-9-]*)/.exec(value.slice(i, i + 64))?.[1]?.toLowerCase();
+    let j = i + 1;
+    while (j < value.length && value[j] !== ">") {
+      if (value[j] === '"' || value[j] === "'") {
+        const end = skipQuoted(value, j);
+        if (end < 0) return true;
+        j = end;
+        continue;
+      }
+      j += 1;
+    }
+    i = j + 1;
+    if (name && RAW_TEXT_ELEMENTS.has(name)) {
+      const close = lower.indexOf(`</${name}`, i);
+      const end = close < 0 ? value.length : close;
+      if (/(?<!\\)\\[nr]/.test(value.slice(i, end))) return true;
+      i = end;
+    }
+  }
+  return false;
+}
+
+const LITERAL_HOLDS_ESCAPE: Readonly<Record<SourceLanguage, (value: string) => boolean>> = {
+  html: htmlLiteralHoldsEscape,
+  css: cssLiteralHoldsEscape,
+  js: jsLiteralHoldsEscape,
+};
+
+/** An escaped line break (`\n`, `\r\n`) not preceded by another backslash. */
+const ESCAPED_LINE_BREAK = /(?<!\\)(?:\\r)?\\n/g;
+
+/**
+ * True when a source value's line breaks were string-escaped as a whole:
+ * no real line break at all, at least two escaped ones, one of them
+ * followed by indentation (the signature of pretty-printed source), and
+ * none inside a literal of `language` (see the file comment).
+ *
+ * @param value - the source text as sent.
+ * @param language - the grammar the value is written in.
+ */
+export function hasEscapedLineBreaks(value: string, language: SourceLanguage): boolean {
+  if (/[\r\n]/.test(value)) return false;
+  const hits = value.match(ESCAPED_LINE_BREAK)?.length ?? 0;
+  if (hits < 2) return false;
+  if (!/(?<!\\)\\n(?:[ \t]|\\t)/.test(value)) return false;
+  return !LITERAL_HOLDS_ESCAPE[language](value);
+}
+
+/**
+ * The value with every escaped line break turned back into a real one (and
+ * the escaped tabs indenting the next line into real tabs) when
+ * `hasEscapedLineBreaks` holds; the input unchanged otherwise. Nothing else
+ * is unescaped: quotes and backslashes arrived as they were meant.
+ *
+ * @param value - the tool argument (non-strings pass through).
+ * @param language - the grammar the value is written in.
+ */
+export function decodeEscapedLineBreaks(value: unknown, language: SourceLanguage): unknown {
+  if (typeof value !== "string" || !hasEscapedLineBreaks(value, language)) return value;
+  return value.replace(
+    /(?<!\\)(?:\\r)?\\n((?:\\t)*)/g,
+    (_m, tabs: string) => `\n${"\t".repeat(tabs.length / 2)}`,
+  );
+}

package/src/index.ts

@@ -14,11 +14,13 @@ export * from "./content.js";
 export * from "./context.js";
 export * from "./css-gradient-scan.js";
 export * from "./css-scope-scan.js";
+export * from "./css-var-aliases.js";
 export * from "./css-var-scan.js";
 export * from "./database-url.js";
 export * from "./design-draft-shell.js";
 export * from "./document-language.js";
 export * from "./edit-markers.js";
+export * from "./escaped-line-breaks.js";
 export * from "./font-assets.js";
 export * from "./font-axis-policy.js";
 export * from "./font-usage.js";
@@ -32,6 +34,7 @@ export * from "./image-capabilities.js";
 export * from "./interactions.js";
 export * from "./link-canonicalise.js";
 export * from "./link-refs.js";
+export * from "./lists/index.js";
 export {
   type LogContext,
   type Logger,
@@ -72,11 +75,11 @@ export * from "./screenshot-capture.js";
 export * from "./seo.js";
 export * from "./skills.js";
 export * from "./snapshots.js";
+export * from "./source-text-transport.js";
 export * from "./staging-gate.js";
 export * from "./static-cache-policy.js";
 export * from "./static-security-headers.js";
 export * from "./strip-cdata.js";
-export * from "./structured-sets.js";
 export * from "./subagents.js";
 export * from "./template-engine.js";
 export * from "./theme-importers/auto-detect.js";