@caelo-cms/shared 0.10.72 → 0.11.0

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/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";
@@ -32,6 +33,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 +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";

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) ||

package/src/link-refs.test.ts

@@ -25,10 +25,31 @@ import {
   parseLinkRef,
   resolveLinkRefsInHtml,
 } from "./link-refs.js";
+import { DEFAULT_LIST_TYPES } from "./lists/default-types.js";
+import { createListRenderContext } from "./lists/resolve.js";
 import { renderPlacedModule } from "./nested-module-render.js";
 import { composePageWithLayout } from "./preview-compose.js";
 import { renderTemplate } from "./template-engine.js";
 
+/** A list context that knows only the shipped list types (local lists need nothing else). */
+const lists = createListRenderContext({
+  listTypes: new Map(DEFAULT_LIST_TYPES.map((t, i) => [t.slug, { id: `t${i}`, def: t }])),
+  lists: new Map(),
+  pageTypes: new Map(),
+  pages: new Map(),
+  media: new Map(),
+  siteLanguage: "en",
+}).forPage(null);
+const uid = (n: number) => `00000000-0000-4000-9000-${String(n).padStart(12, "0")}`;
+const links = (...ls: [string, string][]) =>
+  ls.map(([label, href], i) => ({
+    id: uid(i + 1),
+    node: "link",
+    values: { label, link: { href } },
+  }));
+const unstamp = (html: string) => html.replace(/ data-caelo-list-item="[^"]*"/g, "");
+const NAV_HTML = '<nav>{{#nav}}<a href="{{link}}">{{label}}</a>{{/nav}}</nav>';
+
 const PAGE = "11111111-1111-4111-8111-111111111111";
 const DRAFT = "22222222-2222-4222-8222-222222222222";
 const GONE = "33333333-3333-4333-8333-333333333333";
@@ -172,25 +193,26 @@ describe("resolution", () => {
 describe("template engine — references resolve wherever they come from", () => {
   const resolver = () => index().forPage(null);
 
-  it("resolves module HTML attributes, values, defaults and link-list items", () => {
+  it("resolves module HTML attributes, values, defaults and list entries", () => {
     const r = renderTemplate({
-      html: `<a href="caelo:page/${PAGE}">Home</a><a href="{{cta_href}}">{{cta_label}}</a><img src="{{hero}}">{{#nav}}<a href="{{href}}">{{label}}</a>{{/nav}}<div>{{body}}</div>`,
+      html: `<a href="caelo:page/${PAGE}">Home</a><a href="{{cta_href}}">{{cta_label}}</a><img src="{{hero}}">{{#nav}}<a href="{{link}}">{{label}}</a>{{/nav}}<div>{{body}}</div>`,
       fields: [
         { name: "cta_href", kind: "url", default: `caelo:page/${PAGE}#contact` },
         { name: "cta_label", kind: "text" },
         { name: "hero", kind: "image" },
-        { name: "nav", kind: "link-list" },
+        { name: "nav", kind: "list", listType: "links" },
         { name: "body", kind: "richtext" },
       ],
       contentValues: {
         cta_label: "Talk to us",
         hero: `caelo:media/${MEDIA}`,
-        nav: [{ label: "Pricing", href: `caelo:page/${DRAFT}` }],
+        nav: links(["Pricing", `caelo:page/${DRAFT}`]),
         body: `<p>See <a href="caelo:page/${PAGE}?x=1">about</a></p>`,
       },
+      lists,
       linkResolver: resolver(),
     });
-    expect(r.html).toBe(
+    expect(unstamp(r.html)).toBe(
       '<a href="/company/about/">Home</a><a href="/company/about/#contact">Talk to us</a>' +
         '<img src="/_caelo/media/hero-shot"><a href="/pricing/">Pricing</a>' +
         '<div><p>See <a href="/company/about/?x=1">about</a></p></div>',
@@ -241,8 +263,8 @@ describe("template engine — references resolve wherever they come from", () =>
   });
 });
 
-describe("composer — nav-menu sets and pre-rendered modules", () => {
-  it("resolves nav-menu item hrefs and attributes a broken one to the nav module", () => {
+describe("composer — chrome lists and pre-rendered modules", () => {
+  it("resolves a chrome module's list entries and attributes a broken one to the module", () => {
     const out = composePageWithLayout({
       layoutHtml:
         '<html><head></head><body><caelo-slot name="header"></caelo-slot><caelo-slot name="content"></caelo-slot></body></html>',
@@ -253,11 +275,19 @@ describe("composer — nav-menu sets and pre-rendered modules", () => {
           modules: [
             {
               moduleId: "m-nav",
-              slug: "nav-menu-main",
+              slug: "main-nav",
               displayName: "Nav",
-              html: "",
+              html: NAV_HTML,
               css: "",
               js: "",
+              fields: [
+                {
+                  name: "nav",
+                  kind: "list",
+                  listType: "links",
+                  default: links(["About", `caelo:page/${PAGE}`], ["Gone", `caelo:page/${GONE}`]),
+                },
+              ],
             },
           ],
         },
@@ -279,23 +309,16 @@ describe("composer — nav-menu sets and pre-rendered modules", () => {
           ],
         },
       ],
-      structuredSets: {
-        byKindSlug: {
-          "nav-menu/main": [
-            { label: "About", href: `caelo:page/${PAGE}` },
-            { label: "Gone", href: `caelo:page/${GONE}` },
-          ],
-        },
-      },
+      lists,
       linkResolver: index().forPage(PAGE),
     });
-    expect(out.html).toContain('<a href="/company/about/">About</a>');
+    expect(unstamp(out.html)).toContain('<a href="/company/about/">About</a>');
     expect(out.html).toContain(`href="caelo:page/${GONE}"`);
     expect(out.moduleFailures).toEqual([
       {
         blockName: "header",
         moduleId: "m-nav",
-        moduleSlug: "nav-menu-main",
+        moduleSlug: "main-nav",
         field: "",
         reason: `link-target-missing:page/${GONE}`,
       },
@@ -314,7 +337,6 @@ describe("composer — nav-menu sets and pre-rendered modules", () => {
       templateHtml: '<caelo-slot name="content"></caelo-slot>',
       templateCss: "",
       blocks: [],
-      structuredSets: { byKindSlug: {} },
       linkResolver: index().forPage(PAGE),
     });
     expect(out.html).toContain('<a class="home" href="/company/about/#top">Home</a>');
@@ -631,25 +653,23 @@ describe("page variants (link-resolve) — links go to the rendering page's vari
     });
   });
 
-  it("covers HTML href, rich text, link field and link-list in one render", () => {
+  it("covers HTML href, rich text, link field and list entries in one render", () => {
     const r = renderTemplate({
-      html: `<a href="caelo:page/${EN_HOME}">Home</a><a href="{{cta_href}}">Go</a>{{#nav}}<a href="{{href}}">{{label}}</a>{{/nav}}<div>{{body}}</div>`,
+      html: `<a href="caelo:page/${EN_HOME}">Home</a><a href="{{cta_href}}">Go</a>{{#nav}}<a href="{{link}}">{{label}}</a>{{/nav}}<div>{{body}}</div>`,
       fields: [
         { name: "cta_href", kind: "link" },
-        { name: "nav", kind: "link-list" },
+        { name: "nav", kind: "list", listType: "links" },
         { name: "body", kind: "richtext" },
       ],
       contentValues: {
         cta_href: `caelo:page/${EN_PRICING}#plans`,
-        nav: [
-          { label: "About", href: `caelo:page/${EN_ABOUT}` },
-          { label: "Solo", href: `caelo:page/${EN_SOLO}` },
-        ],
+        nav: links(["About", `caelo:page/${EN_ABOUT}`], ["Solo", `caelo:page/${EN_SOLO}`]),
         body: `<p><a href="caelo:page/${EN_ABOUT}?x=1">about</a></p>`,
       },
+      lists,
       linkResolver: variantIndex("preview").forPage(DE_PRICING),
     });
-    expect(r.html).toBe(
+    expect(unstamp(r.html)).toBe(
       '<a href="/de/">Home</a><a href="/de/preise/#plans">Go</a>' +
         `<a href="/de/ueber/">About</a><a href="caelo:page/${EN_SOLO}">Solo</a>` +
         '<div><p><a href="/de/ueber/?x=1">about</a></p></div>',
@@ -657,7 +677,7 @@ describe("page variants (link-resolve) — links go to the rendering page's vari
     expect(r.missingSlots).toEqual([`link-variant-missing:page/${EN_SOLO}:de`]);
   });
 
-  it("covers nav-menu sets in the composer and attributes a missing sibling to the nav", () => {
+  it("covers chrome lists in the composer and attributes a missing sibling to the module", () => {
     const out = composePageWithLayout({
       layoutHtml:
         '<html><head></head><body><caelo-slot name="header"></caelo-slot><caelo-slot name="content"></caelo-slot></body></html>',
@@ -668,11 +688,22 @@ describe("page variants (link-resolve) — links go to the rendering page's vari
           modules: [
             {
               moduleId: "m-nav",
-              slug: "nav-menu-main",
+              slug: "main-nav",
               displayName: "Nav",
-              html: "",
+              html: NAV_HTML,
               css: "",
               js: "",
+              fields: [
+                {
+                  name: "nav",
+                  kind: "list",
+                  listType: "links",
+                  default: links(
+                    ["About", `caelo:page/${EN_ABOUT}`],
+                    ["Solo", `caelo:page/${EN_SOLO}`],
+                  ),
+                },
+              ],
             },
           ],
         },
@@ -680,22 +711,15 @@ describe("page variants (link-resolve) — links go to the rendering page's vari
       templateHtml: '<caelo-slot name="content"></caelo-slot>',
       templateCss: "",
       blocks: [],
-      structuredSets: {
-        byKindSlug: {
-          "nav-menu/main": [
-            { label: "About", href: `caelo:page/${EN_ABOUT}` },
-            { label: "Solo", href: `caelo:page/${EN_SOLO}` },
-          ],
-        },
-      },
+      lists,
       linkResolver: variantIndex().forPage(DE_ABOUT),
     });
-    expect(out.html).toContain('<a href="/de/ueber/">About</a>');
+    expect(unstamp(out.html)).toContain('<a href="/de/ueber/">About</a>');
     expect(out.moduleFailures).toEqual([
       {
         blockName: "header",
         moduleId: "m-nav",
-        moduleSlug: "nav-menu-main",
+        moduleSlug: "main-nav",
         field: "",
         reason: `link-variant-missing:page/${EN_SOLO}:de`,
       },
@@ -745,7 +769,7 @@ describe("link failure markers — what the build gate and the preview report",
 
   it("leaves every other marker alone, in order", () => {
     expect(isLinkFailureMarker("field-not-declared:x")).toBe(false);
-    expect(isLinkFailureMarker("link-list-malformed:nav[0]")).toBe(false);
+    expect(isLinkFailureMarker("list-malformed:nav[items[0]]")).toBe(false);
     expect(
       linkMarkersOf([
         "theme-asset-unbound:logo",

package/src/link-refs.ts

@@ -9,8 +9,8 @@
  * rendered for. Renaming or moving a page then changes no stored link.
  *
  * Grammar (one form for every place a link can live — `link` / `url`
- * fields, `link-list` items, `*_href` values, module HTML attributes,
- * rich text, structured-set items, field defaults):
+ * fields, list entry `link` values, `*_href` values, module HTML attributes,
+ * rich text, field defaults):
  *
  *   caelo:page/<pageId>[?query][#anchor]
  *   caelo:media/<mediaId>[/<variant>]
@@ -277,7 +277,7 @@ export function replaceLinkRefs(
 }
 
 /**
- * Walk a JSON value (content values, field defaults, set items) and map
+ * Walk a JSON value (content values, field defaults, list entries) and map
  * every string through {@link replaceLinkRefs}. Returns the SAME
  * reference when nothing changed, so callers can cheaply detect no-ops.
  */

package/src/lists/address.ts

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Stable value addresses (epic #1107, `docs/lists.md` §9). Core has no
+ * locale concept; a translation plugin keys its own storage by these
+ * addresses and answers the `list-resolve` composition point with
+ * overlays keyed the same way. Entry ids never change, so an address
+ * survives moves, renames of loop names and reordering.
+ */
+
+/** One addressable stored value. */
+export type ValueAddress =
+  | {
+      readonly kind: "list";
+      readonly listId: string;
+      readonly itemId: string;
+      readonly field: string;
+    }
+  | {
+      readonly kind: "instance";
+      readonly contentInstanceId: string;
+      readonly field: string;
+      readonly itemId: string;
+      readonly itemField: string;
+    }
+  | { readonly kind: "pageProp"; readonly pageId: string; readonly field: string }
+  | {
+      readonly kind: "listTypeField";
+      readonly listTypeId: string;
+      readonly node: string;
+      readonly field: string;
+    };
+
+const SEG = "[a-z0-9_-]+";
+const ADDRESS_RE = new RegExp(
+  `^(?:list/(${SEG})/item/(${SEG})/(${SEG})` +
+    `|instance/(${SEG})/(${SEG})/item/(${SEG})/(${SEG})` +
+    `|page/(${SEG})/props/(${SEG})` +
+    `|list_type/(${SEG})/node/(${SEG})/(${SEG}))$`,
+);
+
+/** Format an address as its canonical string. */
+export function formatValueAddress(a: ValueAddress): string {
+  switch (a.kind) {
+    case "list":
+      return `list/${a.listId}/item/${a.itemId}/${a.field}`;
+    case "instance":
+      return `instance/${a.contentInstanceId}/${a.field}/item/${a.itemId}/${a.itemField}`;
+    case "pageProp":
+      return `page/${a.pageId}/props/${a.field}`;
+    case "listTypeField":
+      return `list_type/${a.listTypeId}/node/${a.node}/${a.field}`;
+  }
+}
+
+/** Parse an address string; null when it is not one. */
+export function parseValueAddress(s: string): ValueAddress | null {
+  const m = ADDRESS_RE.exec(s);
+  if (!m) return null;
+  if (m[1] && m[2] && m[3]) return { kind: "list", listId: m[1], itemId: m[2], field: m[3] };
+  if (m[4] && m[5] && m[6] && m[7]) {
+    return {
+      kind: "instance",
+      contentInstanceId: m[4],
+      field: m[5],
+      itemId: m[6],
+      itemField: m[7],
+    };
+  }
+  if (m[8] && m[9]) return { kind: "pageProp", pageId: m[8], field: m[9] };
+  if (m[10] && m[11] && m[12]) {
+    return { kind: "listTypeField", listTypeId: m[10], node: m[11], field: m[12] };
+  }
+  return null;
+}