@caelo-cms/shared 0.10.71 → 0.11.0

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/id-safe-truncate.test.ts

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import { idSafeCutIndex, truncateKeepingIds } from "./id-safe-truncate.js";
+
+const ID = "c9c7ddcb-cc85-4747-84fa-90967da6f769";
+
+describe("idSafeCutIndex (#1094)", () => {
+  it("moves a cut inside a UUID back to just before it", () => {
+    const text = `ref ${ID} tail`;
+    // 4 = where the id starts; every cut inside it lands there.
+    for (let at = 5; at < 4 + ID.length; at++) expect(idSafeCutIndex(text, at)).toBe(4);
+  });
+
+  it("keeps a cut that does not split an id", () => {
+    const text = `ref ${ID} tail`;
+    expect(idSafeCutIndex(text, 4)).toBe(4);
+    expect(idSafeCutIndex(text, 4 + ID.length)).toBe(4 + ID.length);
+    expect(idSafeCutIndex("plain text here", 5)).toBe(5);
+  });
+});
+
+describe("truncateKeepingIds", () => {
+  it("never leaves a UUID fragment before the suffix", () => {
+    const text = `contentInstanceId: ${ID}, more`;
+    const out = truncateKeepingIds(text, 45);
+    expect(out).toBe("contentInstanceId: …");
+    expect(truncateKeepingIds(text, 80)).toBe(text);
+  });
+
+  it("keeps a whole id that fits", () => {
+    const text = `id ${ID} and a long trailing explanation`;
+    expect(truncateKeepingIds(text, 3 + ID.length + 2)).toBe(`id ${ID} …`);
+  });
+});

package/src/id-safe-truncate.ts

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Cut text for the AI without ever cutting an id in half.
+ *
+ * #1089 / #1094 — the model called tools with UUIDs one character short
+ * (`c9c7ddcb-cc85-4747-84f-90967da6f769`). Every place that shortens text
+ * the AI reads (compacted tool results, digests, previews, capped finding
+ * messages) used a plain `slice(0, n)`, so an id straddling the cut reached
+ * the model as a fragment it then "completed" from memory. An id is copied,
+ * never reconstructed: the cut moves back to just before an id it would
+ * split, so an id is either shown whole or not at all.
+ */
+
+const UUID_PATTERN = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi;
+
+/**
+ * The largest index `<= at` at which `text` can be cut without splitting
+ * a UUID.
+ *
+ * @param at - the desired cut index (characters kept).
+ */
+export function idSafeCutIndex(text: string, at: number): number {
+  if (at <= 0) return 0;
+  if (at >= text.length) return text.length;
+  // Only an id that could reach the cut matters: scan a window around it.
+  const from = Math.max(0, at - 36);
+  const window = text.slice(from, at + 36);
+  for (const m of window.matchAll(UUID_PATTERN)) {
+    const start = from + (m.index ?? 0);
+    const end = start + m[0].length;
+    if (start < at && at < end) return start;
+  }
+  return at;
+}
+
+/**
+ * `text` cut to at most `max` characters (the suffix included) without
+ * splitting a UUID; unchanged when it already fits.
+ *
+ * @param suffix - appended when cut (default `…`).
+ */
+export function truncateKeepingIds(text: string, max: number, suffix = "…"): string {
+  if (text.length <= max) return text;
+  return `${text.slice(0, idSafeCutIndex(text, Math.max(0, max - suffix.length)))}${suffix}`;
+}

package/src/index.ts

@@ -14,6 +14,7 @@ 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";
@@ -27,10 +28,12 @@ export * from "./genesis.js";
 export * from "./genesis-inventory.js";
 export * from "./google-models.js";
 export * from "./google-oauth.js";
+export * from "./id-safe-truncate.js";
 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,
@@ -71,11 +74,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";
@@ -92,6 +95,7 @@ export * from "./themes.js";
 export * from "./themes-errors.js";
 export * from "./untrusted-tool-result.js";
 export * from "./url.js";
+export * from "./uuid-diagnose.js";
 export {
   CAELO_VERSION,
   CALEO_VERSION,

package/src/interactions.ts

@@ -32,7 +32,7 @@ export interface InteractionSnippet {
   readonly js: string;
 }
 
-/** Functional-only rules for the built-in nav renderer: collapse/expand, zero aesthetics. */
+/** Functional-only rules for a collapsible nav (`mobile-nav`): collapse/expand, zero aesthetics. */
 const MOBILE_NAV_CSS =
   ".caelo-nav-menu .caelo-nav-toggle{display:none;background:none;border:0;cursor:pointer;padding:0.5rem;color:inherit;font:inherit}" +
   ".caelo-nav-menu .caelo-nav-toggle .caelo-nav-bar{display:block;width:1.25em;height:2px;background:currentColor;margin:0.25em 0}" +
@@ -199,5 +199,5 @@ export const INTERACTION_MARKUP_CONTRACT =
   '`accordion` (FAQ, collapsible sections): `<div data-caelo-ui="accordion" data-single>` containing `<details id="..."><summary>Question</summary><div>Answer</div></details>` items - `data-single` keeps one open; a link to `#<details id>` opens it. ' +
   '`tabs`: `<div data-caelo-ui="tabs"><div role="tablist" aria-label="..."><button type="button" role="tab" id="t1" aria-controls="p1" aria-selected="true">...</button><button type="button" role="tab" id="t2" aria-controls="p2" aria-selected="false" tabindex="-1">...</button></div><div role="tabpanel" id="p1" aria-labelledby="t1">...</div><div role="tabpanel" id="p2" aria-labelledby="t2" hidden>...</div></div>` - ids must be unique on the page. ' +
   '`carousel` (slider, testimonials): `<section data-caelo-ui="carousel" aria-roledescription="carousel" aria-label="..."><div data-caelo-carousel-track tabindex="0"><div role="group" aria-roledescription="slide" aria-label="1 of 3">...</div>...</div><button type="button" data-caelo-carousel-prev aria-label="Previous slide"><span aria-hidden="true">&lsaquo;</span></button><button type="button" data-caelo-carousel-next aria-label="Next slide"><span aria-hidden="true">&rsaquo;</span></button></section>` (an icon button keeps its visible content aria-hidden; a text button needs no aria-label) - one slide per view by default; set the slides\' `flex-basis` in module CSS to show more. ' +
-  "`mobile-nav` is applied by the built-in nav-menu renderer; never add it by hand. " +
+  '`mobile-nav` (menu collapsing behind a toggle on small screens): `<nav class="caelo-nav-menu" data-caelo-ui="mobile-nav" data-nav-open="false"><button type="button" class="caelo-nav-toggle" aria-expanded="false" aria-label="Menu"><span class="caelo-nav-bar"></span><span class="caelo-nav-bar"></span><span class="caelo-nav-bar"></span></button><ul>{{#menu}}<li>…</li>{{/menu}}</ul></nav>` around the module\'s menu `list` field. ' +
   "Write module JS only for behaviour the kit does not cover.";

package/src/link-canonicalise.test.ts

@@ -349,7 +349,7 @@ describe("HTML and JSON positions", () => {
         { name: "cta", kind: "url" },
         { name: "hero", kind: "image" },
         { name: "price_suffix", kind: "text" },
-        { name: "nav", kind: "link-list" },
+        { name: "nav", kind: "list" },
         { name: "body", kind: "richtext" },
         { name: "card", kind: "module" },
       ],
@@ -357,7 +357,20 @@ describe("HTML and JSON positions", () => {
         cta: "/company/about",
         hero: "/_caelo/media/hero",
         price_suffix: "/month",
-        nav: [{ label: "Home", href: "/" }],
+        nav: [
+          {
+            id: "00000000-0000-4000-9000-000000000001",
+            node: "entry",
+            values: { label: "/company/about", link: { href: "/" } },
+            children: [
+              {
+                id: "00000000-0000-4000-9000-000000000002",
+                node: "entry",
+                values: { label: "Us", link: { href: "/company/about", target: "_blank" } },
+              },
+            ],
+          },
+        ],
         body: '<p><a href="/company/about">us</a></p>',
         card: { moduleId: ABOUT, contentInstanceId: HOME },
         legacy_href: "/company/about",
@@ -368,7 +381,22 @@ describe("HTML and JSON positions", () => {
       cta: `caelo:page/${ABOUT}`,
       hero: `caelo:media/${HERO}`,
       price_suffix: "/month",
-      nav: [{ label: "Home", href: `caelo:page/${HOME}` }],
+      // Entry link values canonicalise at any depth; a label is text even
+      // when it reads like a path.
+      nav: [
+        {
+          id: "00000000-0000-4000-9000-000000000001",
+          node: "entry",
+          values: { label: "/company/about", link: { href: `caelo:page/${HOME}` } },
+          children: [
+            {
+              id: "00000000-0000-4000-9000-000000000002",
+              node: "entry",
+              values: { label: "Us", link: { href: `caelo:page/${ABOUT}`, target: "_blank" } },
+            },
+          ],
+        },
+      ],
       body: `<p><a href="caelo:page/${ABOUT}">us</a></p>`,
       card: { moduleId: ABOUT, contentInstanceId: HOME },
       legacy_href: `caelo:page/${ABOUT}`,
@@ -382,15 +410,17 @@ describe("HTML and JSON positions", () => {
       [
         {
           name: "links",
-          kind: "link-list",
+          kind: "list",
           label: "L",
-          default: [{ label: "A", href: "/company/about" }],
+          default: [{ node: "link", values: { label: "A", link: { href: "/company/about" } } }],
         },
         { name: "title", kind: "text", label: "T", default: "/company/about" },
       ],
       r,
     );
-    expect(fields[0]?.default).toEqual([{ label: "A", href: `caelo:page/${ABOUT}` }]);
+    expect(fields[0]?.default).toEqual([
+      { node: "link", values: { label: "A", link: { href: `caelo:page/${ABOUT}` } } },
+    ]);
     expect(fields[1]?.default).toBe("/company/about");
   });
 });

package/src/link-canonicalise.ts

@@ -14,7 +14,7 @@
  *   - a WHOLE value that is a URL: `url` / `link` / `image` fields, any
  *     field or object key named `href` / `src` / `url` / `link` or ending
  *     in `_href` / `_url` / `_link` / `_src` (`primary_cta_href`), the
- *     `href` of `link-list` items and structured-set items (any depth);
+ *     `href` of a list entry's `link` value (`values.<f>.href`, any depth);
  *   - HTML anywhere (module HTML, rich text, any string value carrying
  *     markup): `href` (pages and media), `src` / `poster` / `srcset`
  *     (media only — a `src="/x"` that is not media is not a page link).
@@ -587,6 +587,11 @@ function canonicaliseFieldValue(
   urlNames: ReadonlySet<string> | undefined,
 ): unknown {
   if (field && NESTED_KINDS.has(field.kind)) return value;
+  // A list (epic #1107) is never a URL as a whole, whatever its name or
+  // where its section sits: its entries decide per value key — a `link`
+  // value's `href` canonicalises, a label stays text. A shared list's
+  // `caelo:list/<id>` is no link at all.
+  if (field?.kind === "list") return canonicaliseJsonLinks(value, run, where, false);
   const asUrl =
     (field !== undefined && URL_KINDS.has(field.kind)) ||
     isLinkKeyName(name) ||