@caelo-cms/shared 0.10.72 → 0.11.1

package/src/content.test.ts

@@ -10,6 +10,7 @@ import {
   pageUpdateSchema,
   slugSchema,
   templateBlocksSetSchema,
+  templateCreateSchema,
 } from "./content.js";
 
 describe("slugSchema", () => {
@@ -90,7 +91,32 @@ describe("moduleCreateSchema", () => {
     expect(moduleCreateSchema.safeParse({ ...base, js: 'xml += "]]>";' }).success).toBe(true);
   });
 
-  it("rejects CDATA on the update path too (edit_module / edit_content funnel)", () => {
+  // e2e-livedit run 40532297620 — html / css whose line breaks arrived as
+  // literal `\n` sequences rendered `\n` text and broke the CSS. AI tool
+  // arguments are decoded first (`decodeEscapedLineBreaks`); every other
+  // writer is refused with the fix.
+  it("rejects html and css whose line breaks are escaped, with the fix", () => {
+    const base = { slug: "site-footer", displayName: "Site footer", html: "<footer></footer>" };
+    const html = moduleCreateSchema.safeParse({
+      ...base,
+      html: '<footer class="f">\\n  <nav>\\n    <a href="/">Home</a>\\n  </nav>\\n</footer>',
+    });
+    expect(html.success).toBe(false);
+    if (!html.success) {
+      expect(html.error.issues.map((i) => i.message).join(" ")).toContain("real line breaks");
+    }
+    const css = moduleUpdateSchema.safeParse({
+      moduleId: "8c2f2f2a-0000-4000-8000-000000000432",
+      css: ".f {\\n  padding: 2rem;\\n}\\n.f a {\\n  color: inherit;\\n}",
+    });
+    expect(css.success).toBe(false);
+    // One escaped newline inside a CSS string on a single line is not the pattern.
+    expect(
+      moduleCreateSchema.safeParse({ ...base, css: '.f::after { content: "\\n  " }' }).success,
+    ).toBe(true);
+  });
+
+  it("rejects CDATA on the update path too (update_modules_many / edit_content funnel)", () => {
     const r = moduleUpdateSchema.safeParse({
       moduleId: "8c2f2f2a-0000-4000-8000-000000000432",
       css: "/*<![CDATA[*/ .x{} /*]]>*/",
@@ -120,8 +146,9 @@ describe("moduleFields numbered-scalar fanout guard (§1A)", () => {
       expect(msg).toContain("numbered-scalar fanout");
       expect(msg).toContain('"label", "label2", "label3"');
       // AI-actionable: the error names every list-kind fix.
-      expect(msg).toContain("text-list");
-      expect(msg).toContain("link-list");
+      expect(msg).toContain('kind "list"');
+      expect(msg).toContain('listType "texts"');
+      expect(msg).toContain('"links"');
       expect(msg).toContain("module-list");
       expect(msg).toContain("§1A");
     }
@@ -153,11 +180,83 @@ describe("moduleFields numbered-scalar fanout guard (§1A)", () => {
   });
 
   it("scopes to scalar kinds — numbered list fields are a modelling question, not fanout", () => {
-    const linkList = (name: string) => ({ name, kind: "link-list", label: name });
+    const linkList = (name: string) => ({ name, kind: "list", listType: "links", label: name });
     expect(mod([linkList("links1"), linkList("links2"), linkList("links3")]).success).toBe(true);
   });
 });
 
+// Epic #1107 — the `list` field kind (docs/lists.md §7): the static
+// schema checks the binding's shape; fitting the type is the op's job.
+describe("moduleFields list kind", () => {
+  const mod = (fields: unknown) =>
+    moduleCreateSchema.safeParse({ slug: "m", displayName: "M", html: "<div></div>", fields });
+  const LIST = "caelo:list/00000000-0000-4000-8000-000000000101";
+  const messages = (r: ReturnType<typeof mod>) =>
+    r.success ? [] : r.error.issues.map((i) => i.message);
+
+  it("accepts every binding", () => {
+    const ok = mod([
+      {
+        name: "bullets",
+        label: "B",
+        kind: "list",
+        listType: "texts",
+        default: [{ node: "text", values: { text: "x" } }],
+      },
+      { name: "menu", label: "M", kind: "list", listType: "menu", bind: "shared", list: LIST },
+      {
+        name: "footer",
+        label: "F",
+        kind: "list",
+        listType: "links",
+        bind: "shared",
+        default: LIST,
+      },
+      {
+        name: "latest",
+        label: "L",
+        kind: "list",
+        listType: "links",
+        bind: "source",
+        source: {
+          kind: "query",
+          editable: ["limit"],
+          defaults: { page_type: "news", order: "published_desc", limit: 3 },
+        },
+      },
+      {
+        name: "crumbs",
+        label: "C",
+        kind: "list",
+        listType: "links",
+        bind: "source",
+        source: { kind: "system", name: "breadcrumbs" },
+      },
+    ]);
+    expect(ok.success).toBe(true);
+  });
+
+  it("refuses bindings whose parts do not fit together, naming the fix", () => {
+    const r = mod([
+      { name: "a", label: "A", kind: "list", listType: "menu", bind: "source" },
+      { name: "b", label: "B", kind: "list", listType: "menu", list: LIST },
+      { name: "c", label: "C", kind: "list", listType: "menu", bind: "shared", default: [] },
+      { name: "d", label: "D", kind: "list", listType: "texts", default: LIST },
+    ]);
+    expect(messages(r)).toEqual([
+      'list field "a": bind "source" needs a source (query, system or plugin).',
+      'list field "b": list is only allowed with bind "shared" — a local list stores its entries in the placement.',
+      'list field "c": a shared default is caelo:list/<id> — create the list with upsert_lists_many first.',
+      'list field "d": a local default is an array of entries, not a list reference.',
+    ]);
+  });
+
+  it("refuses the removed text-list / link-list kinds", () => {
+    expect(mod([{ name: "t", label: "T", kind: "text-list" }]).success).toBe(false);
+    expect(mod([{ name: "l", label: "L", kind: "link-list" }]).success).toBe(false);
+  });
+});
+
 describe("pageCreateSchema (no raw HTML invariant)", () => {
   it("accepts a structured page payload", () => {
     const r = pageCreateSchema.safeParse({
@@ -250,3 +349,37 @@ describe("templateBlocksSetSchema", () => {
     expect(r.success).toBe(true);
   });
 });
+
+describe("corrupted code payloads are refused at the boundary (PR #1121 e2e)", () => {
+  const base = { slug: "footer", displayName: "Footer", html: "<footer>x</footer>" };
+  it("refuses JSON-encoded html and css with the fix in the message", () => {
+    const html = moduleCreateSchema.safeParse({
+      ...base,
+      html: JSON.stringify('<footer class="x">{{#links}}{{label}}{{/links}}</footer>'),
+    });
+    expect(html.success).toBe(false);
+    expect(html.error?.issues[0]?.message).toContain("JSON-encoded");
+    const css = moduleCreateSchema.safeParse({
+      ...base,
+      css: JSON.stringify(".x { color: red; }"),
+    });
+    expect(css.success).toBe(false);
+  });
+  it("refuses HTML-escaped template markup", () => {
+    const r = templateCreateSchema.safeParse({
+      slug: "page",
+      displayName: "Page",
+      html: '&lt;div&gt;&lt;caelo-slot name="content"&gt;&lt;/caelo-slot&gt;&lt;/div&gt;',
+    });
+    expect(r.success).toBe(false);
+    expect(r.error?.issues[0]?.message).toContain("HTML-escaped");
+  });
+  it("keeps legitimate markup: entities inside real tags, a quote-led text node", () => {
+    expect(
+      moduleCreateSchema.safeParse({ ...base, html: "<pre>&lt;div&gt; is a tag</pre>" }).success,
+    ).toBe(true);
+    expect(moduleCreateSchema.safeParse({ ...base, html: '"Quoted" <em>text</em>' }).success).toBe(
+      true,
+    );
+  });
+});

package/src/content.ts

@@ -11,6 +11,10 @@
  */
 
 import { z } from "zod";
+import { hasEscapedLineBreaks } from "./escaped-line-breaks.js";
+import { listItemInputSchema } from "./lists/items.js";
+import { LIST_MAX_ITEMS, sourceDefSchema } from "./lists/list-type.js";
+import { LIST_REF_RE } from "./lists/refs.js";
 
 /** Lowercase slug, hyphenated, 1–64 chars, no leading/trailing hyphen. */
 export const slugSchema = z
@@ -93,7 +97,69 @@ export const MODULE_JS_MAX = 256 * 1024;
 export const TEMPLATE_HTML_MAX = 512 * 1024;
 export const TEMPLATE_CSS_MAX = 128 * 1024;
 
-const moduleHtml = z.string().max(MODULE_HTML_MAX, `html exceeds ${MODULE_HTML_MAX} bytes`);
+/**
+ * Code payloads a model sometimes corrupts before they reach us, both seen
+ * in PR #1121's real-AI runs and stored verbatim before this guard:
+ * - JSON-encoded: the whole value wrapped in quotes with `\"` escapes
+ *   (`"<footer class=\"x\">…"`) — the page showed literal quotes;
+ * - HTML-escaped markup: `&lt;div&gt;&lt;caelo-slot …` with no real tag
+ *   — a template without a single slot, so it had no blocks at all.
+ * Refusing at the write boundary with the fix turns a broken render the
+ * AI only notices from a screenshot into one corrected call (CLAUDE.md
+ * §2, §11; same reasoning as the CDATA guard below). AI tool arguments
+ * never reach this in that shape: `sourceTextArg` decodes both encodings
+ * first (`source-text-transport.ts`); this guards every other writer.
+ */
+export function jsonEncodedCodeMessage(field: string, value: string): string | null {
+  const t = value.trim();
+  if (t.length < 2 || !t.startsWith('"') || !t.endsWith('"')) return null;
+  try {
+    if (typeof JSON.parse(t) !== "string") return null;
+  } catch {
+    return null;
+  }
+  return `${field} is JSON-encoded (wrapped in quotes with \\" escapes) — send the raw ${field} itself, not a JSON string of it.`;
+}
+
+/** See {@link jsonEncodedCodeMessage}: markup sent HTML-escaped. */
+export function htmlEscapedMarkupMessage(field: string, value: string): string | null {
+  if (value.includes("<") || !/&lt;\/?[a-zA-Z]/.test(value)) return null;
+  return `${field} is HTML-escaped (&lt;…&gt; instead of <…>) — send the markup itself, unescaped.`;
+}
+
+/**
+ * See {@link jsonEncodedCodeMessage}: source whose line breaks arrived as
+ * literal `\n` sequences (`hasEscapedLineBreaks`) — the page shows the
+ * `\n` text and the CSS rules after it break. AI tool arguments are decoded
+ * first (`decodeEscapedLineBreaks`); this guards every other writer. Module
+ * js is checked by parsing it (admin-core `module-js-syntax.ts`), which
+ * catches this and every other syntax error.
+ */
+export function escapedLineBreaksMessage(field: "html" | "css", value: string): string | null {
+  if (!hasEscapedLineBreaks(value, field)) return null;
+  return `${field} has its line breaks escaped (literal \\n sequences, no real line break) — send the ${field} with real line breaks.`;
+}
+
+const noCorruptMarkup = (field: "html") => (value: string, ctx: z.RefinementCtx) => {
+  const message =
+    jsonEncodedCodeMessage(field, value) ??
+    htmlEscapedMarkupMessage(field, value) ??
+    escapedLineBreaksMessage(field, value);
+  if (message) ctx.addIssue({ code: "custom", message });
+};
+const noJsonEncodedCode = (field: string) => (value: string, ctx: z.RefinementCtx) => {
+  const message = jsonEncodedCodeMessage(field, value);
+  if (message) ctx.addIssue({ code: "custom", message });
+};
+const noCorruptCss = (value: string, ctx: z.RefinementCtx) => {
+  const message = jsonEncodedCodeMessage("css", value) ?? escapedLineBreaksMessage("css", value);
+  if (message) ctx.addIssue({ code: "custom", message });
+};
+
+const moduleHtml = z
+  .string()
+  .max(MODULE_HTML_MAX, `html exceeds ${MODULE_HTML_MAX} bytes`)
+  .superRefine(noCorruptMarkup("html"));
 
 /**
  * issue #432 root-cause guard — reject XML CDATA wrappers in module css/js.
@@ -122,11 +188,13 @@ const cdataMessage = (field: "css" | "js"): string =>
 const moduleCss = z
   .string()
   .max(MODULE_CSS_MAX, `css exceeds ${MODULE_CSS_MAX} bytes`)
-  .refine(noCdata, cdataMessage("css"));
+  .refine(noCdata, cdataMessage("css"))
+  .superRefine(noCorruptCss);
 const moduleJs = z
   .string()
   .max(MODULE_JS_MAX, `js exceeds ${MODULE_JS_MAX} bytes`)
-  .refine(noCdata, cdataMessage("js"));
+  .refine(noCdata, cdataMessage("js"))
+  .superRefine(noJsonEncodedCode("js"));
 
 /**
  * v0.4.0 — module field schema. Each field declares one substitution slot in
@@ -161,29 +229,29 @@ export const MODULE_FIELD_PRIMITIVE_KINDS = [
 ] as const;
 
 /**
- * v0.12.0 — list-of-primitive field kinds. The grammar mirrors
- * `module-list`'s `{{#field}}{{/field}}` iteration but the elements
- * are primitives (or a fixed {label,href} pair for link-list), not
- * `{moduleId, contentInstanceId}` refs.
- *
- * Use `text-list` for "list of strings" — menu labels, tag chips,
- * bullet points where each item is just text. Inner template
- * references `{{.}}` (Mustache convention) or `{{item}}` to mean
- * the current element.
+ * Epic #1107 — the data-list field kind (`docs/lists.md` §7). One kind
+ * for every repeated piece of data: feature bullets, a footer link group,
+ * a three-level menu, a mega dropdown, a "latest news" block. The entry
+ * shape comes from a LIST TYPE (`listType`, a slug); the entries come from
+ * the field's binding:
  *
- * Use `link-list` for "list of links" — primary nav, footer columns,
- * sidebar menus. Each element is `{href, label}`. Inner template
- * uses `{{href}}` + `{{label}}` per iteration.
+ *   - `local`  (default) — entries stored in the placement's value
+ *                          (`ListItem[]`), only this module shows them;
+ *   - `shared` — a `caelo:list/<id>` list, fixed on the field (`list`) or
+ *                chosen per placement; navigation and anything needed in
+ *                more than one place;
+ *   - `source` — entries generated per page from `source` (a page query,
+ *                a system source like breadcrumbs, a plugin source).
  *
- * For lists with richer per-item structure (cards with image + title
- * + body + CTA), use `module-list` pointing at a sub-module — that's
- * what nested modules are for.
+ * The template iterates `{{#field}}…{{/field}}` the same way for every
+ * binding. `module-list` stays: it composes modules, lists carry data.
+ * Replaces the `text-list` / `link-list` kinds.
  */
-export const MODULE_FIELD_LIST_KINDS = ["text-list", "link-list"] as const;
+export const MODULE_FIELD_LIST_KINDS = ["list"] as const;
 
 export const MODULE_FIELD_NESTED_KINDS = ["module", "module-list"] as const;
 
-/** All eleven v0.12.0 kinds. */
+/** Every module field kind. */
 export const MODULE_FIELD_KINDS = [
   ...MODULE_FIELD_PRIMITIVE_KINDS,
   ...MODULE_FIELD_LIST_KINDS,
@@ -200,10 +268,9 @@ export type ModuleFieldKind = (typeof MODULE_FIELD_KINDS)[number];
 
 /**
  * Field kinds the shared template engine iterates via the
- * `{{#name}}…{{/name}}` Mustache-section operator. Adding a new
- * list-shaped kind to MODULE_FIELD_LIST_KINDS / MODULE_FIELD_NESTED_KINDS
- * automatically extends this set; the engine's section-dispatch branch
- * keys off it (`packages/shared/src/template-engine.ts`).
+ * `{{#name}}…{{/name}}` Mustache-section operator (`list` and
+ * `module-list`); the engine's section-dispatch keys off it
+ * (`packages/shared/src/template-engine.ts`).
  */
 export const MODULE_FIELD_SECTION_KINDS = [...MODULE_FIELD_LIST_KINDS, "module-list"] as const;
 
@@ -230,7 +297,7 @@ const moduleFieldModuleSchema = z
      * stable `modules.type` class, e.g. `button` — NOT the unique
      * `modules.slug` like `button-mpqxq3ch`). When absent, any module is
      * permitted. The op-layer validator enforces the whitelist against
-     * the referenced module's `type` at `set_content_instance_values`
+     * the referenced module's `type` at `content_instances.set_values`
      * time. v0.12.3 (issue #106) renamed this from `allowedModuleSlugs`:
      * an exact-slug whitelist could never match an AI-minted module
      * because every minted slug carries a uniqueness suffix.
@@ -255,43 +322,84 @@ const moduleFieldModuleListSchema = z
   .strict();
 
 /**
- * v0.12.0 — list-of-strings field. Inner template uses `{{.}}` (or
- * the alias `{{item}}`) to reference the current element. Default
- * is an optional array of strings rendered when the placement's
- * content_instance has no override.
+ * Epic #1107 — a `list` field (`docs/lists.md` §7). The static schema
+ * checks the SHAPE: the binding's parts fit together and a local default
+ * is well-formed entries. Whether those entries fit the named list type
+ * (nodes, fields, depth) needs the type, which is stored data — the op
+ * layer validates that with `validateListItems` when the module is
+ * written, and the renderer reports `list-type-missing:<slug>` for a type
+ * that is gone.
  */
-const moduleFieldTextListSchema = z
+const moduleFieldListSchema = z
   .object({
     name: moduleFieldName,
-    kind: z.literal("text-list"),
+    kind: z.literal("list"),
     label: moduleFieldLabel,
+    /** Slug of the list type that defines the entries. */
+    listType: slugSchema,
+    bind: z.enum(["local", "shared", "source"]).optional(),
+    /** `bind: "shared"` — fix the list for every placement (`caelo:list/<id>`). */
+    list: z.string().regex(LIST_REF_RE, "list must be caelo:list/<id>").optional(),
+    /** `bind: "source"` — where generated entries come from. */
+    source: sourceDefSchema.optional(),
     min: z.number().int().nonnegative().optional(),
-    max: z.number().int().positive().max(256).optional(),
-    default: z.array(z.string()).optional(),
+    max: z.number().int().positive().max(LIST_MAX_ITEMS).optional(),
+    /** `local`: entries; `shared`: `caelo:list/<id>`. */
+    default: z
+      .union([
+        z.array(listItemInputSchema),
+        z.string().regex(LIST_REF_RE, "a shared default must be caelo:list/<id>"),
+      ])
+      .optional(),
   })
   .strict();
 
-/**
- * v0.12.0 — list-of-{label,href} field. Inner template uses
- * `{{label}}` + `{{href}}` per iteration. Targets the common
- * primary-nav / footer-column / sidebar-menu pattern without
- * forcing a sub-module per link.
- */
-const moduleFieldLinkListSchema = z
-  .object({
-    name: moduleFieldName,
-    kind: z.literal("link-list"),
-    label: moduleFieldLabel,
-    min: z.number().int().nonnegative().optional(),
-    max: z.number().int().positive().max(256).optional(),
-    default: z.array(z.object({ label: z.string(), href: z.string() }).strict()).optional(),
-  })
-  .strict();
+/** Binding consistency of one `list` field; every problem, AI-actionable. */
+function listFieldIssues(f: z.infer<typeof moduleFieldListSchema>): string[] {
+  const bind = f.bind ?? "local";
+  const issues: string[] = [];
+  if (bind === "source" && f.source === undefined) {
+    issues.push(`list field "${f.name}": bind "source" needs a source (query, system or plugin).`);
+  }
+  if (bind !== "source" && f.source !== undefined) {
+    issues.push(`list field "${f.name}": source is only allowed with bind "source".`);
+  }
+  if (bind === "local" && f.list !== undefined) {
+    issues.push(
+      `list field "${f.name}": list is only allowed with bind "shared" — a local list stores its entries in the placement.`,
+    );
+  }
+  if (bind === "source" && f.list !== undefined && f.source?.kind !== "system") {
+    issues.push(
+      `list field "${f.name}": list on a source field names the vocabulary of a page_terms source only.`,
+    );
+  }
+  if (f.default !== undefined) {
+    if (bind === "local" && typeof f.default === "string") {
+      issues.push(
+        `list field "${f.name}": a local default is an array of entries, not a list reference.`,
+      );
+    }
+    if (bind === "shared" && Array.isArray(f.default)) {
+      issues.push(
+        `list field "${f.name}": a shared default is caelo:list/<id> — create the list with upsert_lists_many first.`,
+      );
+    }
+    if (bind === "source") {
+      issues.push(
+        `list field "${f.name}": a source field has no default; its entries are generated.`,
+      );
+    }
+  }
+  if (f.min !== undefined && f.max !== undefined && f.min > f.max) {
+    issues.push(`list field "${f.name}": min is greater than max.`);
+  }
+  return issues;
+}
 
 export const moduleFieldSchema = z.discriminatedUnion("kind", [
   moduleFieldPrimitiveSchema,
-  moduleFieldTextListSchema,
-  moduleFieldLinkListSchema,
+  moduleFieldListSchema,
   moduleFieldModuleSchema,
   moduleFieldModuleListSchema,
 ]);
@@ -368,6 +476,11 @@ const moduleFieldsArray = z
         return;
       }
       seen.add(f.name);
+      if (f.kind === "list") {
+        for (const message of listFieldIssues(f)) {
+          ctx.addIssue({ code: z.ZodIssueCode.custom, message });
+        }
+      }
     }
     for (const run of findNumberedScalarFanoutRuns(arr)) {
       ctx.addIssue({
@@ -375,8 +488,9 @@ const moduleFieldsArray = z
         message:
           `numbered-scalar fanout: ${run.map((n) => `"${n}"`).join(", ")} repeat one role as ` +
           "numbered scalar fields — repeating content is ONE list field, never numbered scalars " +
-          '(CLAUDE.md §1A). Replace the run with a single field: kind "text-list" (list of ' +
-          'strings, inner template iterates {{.}}), "link-list" (list of {label, href}), or ' +
+          '(CLAUDE.md §1A). Replace the run with a single field: kind "list" with a list type ' +
+          '(listType "texts" for plain strings — the template iterates {{#f}}{{text}}{{/f}}; ' +
+          '"links" for label + link — {{#f}}<a href="{{link}}">{{label}}</a>{{/f}}), or ' +
           '"module-list" (rich per-item structure: mint a card sub-module and reference it per ' +
           "item — in build_page, author the card detached with `ref` and pass " +
           '[{"$ref": "<ref>"}, …] as the field value). A two-field split like col1/col2 is fine; ' +
@@ -398,7 +512,7 @@ export type ModuleKind = (typeof MODULE_KINDS)[number];
 /**
  * v0.12.0 — description is `.default("")` at the Zod boundary so the
  * 82+ legacy callers in tests/seed scripts keep working unchanged.
- * AI tool descriptions (create_module / edit_module) require the AI
+ * AI tool descriptions (add_module / build_page / update_modules_many) require the AI
  * to supply a real description explicitly — see CLAUDE.md §1A.
  */
 const moduleDescription = z.string().max(1000);
@@ -440,31 +554,29 @@ export const moduleUpdateSchema = z
   })
   .strict();
 
-/**
- * v0.12.0 — page-type tag pages inherit from their template.
- * Constrained by templates_kind_check in migration 0096. Surfaced
- * in the AI's `## Pages` block so the AI sees three modules-on-
- * product-pages as a pattern. See CLAUDE.md §1A.
- */
-export const TEMPLATE_KINDS = [
-  "home",
-  "landing",
-  "product",
-  "blog",
-  "doc",
-  "content",
-  "utility",
-] as const;
-export const templateKindSchema = z.enum(TEMPLATE_KINDS);
-export type TemplateKind = (typeof TEMPLATE_KINDS)[number];
+/** A page type slug (epic #1107, docs/lists.md §5). */
+export const pageTypeSlugSchema = z
+  .string()
+  .regex(
+    /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/,
+    "page type slug: lowercase letters, digits, hyphens",
+  );
 
 export const templateCreateSchema = z
   .object({
     slug: slugSchema,
     displayName: displayNameSchema,
-    /** v0.12.0 — what kind of page binds to this template. */
-    kind: templateKindSchema.default("content"),
-    html: z.string().max(TEMPLATE_HTML_MAX, `html exceeds ${TEMPLATE_HTML_MAX} bytes`),
+    /**
+     * Epic #1107 — the page type (slug) this template serves; the template
+     * is appended to that type's `templates`. Omit for the site's default
+     * page type (`site_defaults.default_page_type_id`, stored data — not a
+     * render-time fallback).
+     */
+    pageType: pageTypeSlugSchema.optional(),
+    html: z
+      .string()
+      .max(TEMPLATE_HTML_MAX, `html exceeds ${TEMPLATE_HTML_MAX} bytes`)
+      .superRefine(noCorruptMarkup("html")),
     css: z.string().max(TEMPLATE_CSS_MAX, `css exceeds ${TEMPLATE_CSS_MAX} bytes`).default(""),
     /**
      * P6.7.6 — every template binds to one layout. When omitted, the
@@ -505,9 +617,9 @@ export const templateUpdateSchema = z
   .object({
     templateId: z.string().uuid(),
     displayName: displayNameSchema.optional(),
-    /** v0.12.0 — re-classify the template's page-type kind. */
-    kind: templateKindSchema.optional(),
-    html: z.string().max(TEMPLATE_HTML_MAX).optional(),
+    /** Epic #1107 — also allow this template for the page type (slug); appended to its `templates`. */
+    pageType: pageTypeSlugSchema.optional(),
+    html: z.string().max(TEMPLATE_HTML_MAX).superRefine(noCorruptMarkup("html")).optional(),
     css: z.string().max(TEMPLATE_CSS_MAX).optional(),
     /** P6.7.6 — re-point the template to a different layout. */
     layoutId: z.string().uuid().optional(),
@@ -536,6 +648,15 @@ export const templateBlocksSetSchema = z
 
 export const pageStatusSchema = z.enum(["draft", "published"]);
 
+/** `pages.short_title` (#1142): a crumb-sized public label, never blank. */
+export const pageShortTitleSchema = z
+  .string()
+  .trim()
+  .min(1, "the short title is the page's breadcrumb label and cannot be blank")
+  // Same bound as the title it is backfilled and defaulted from, so every
+  // stored page stays editable; keeping it crumb-sized is guidance.
+  .max(256);
+
 /**
  * Page payloads are `.strict()` — passing an `html` field is rejected by Zod
  * before the handler runs. This is the §3.1 "no raw HTML on pages" invariant
@@ -545,9 +666,13 @@ export const pageStatusSchema = z.enum(["draft", "published"]);
 export const pageCreateSchema = z
   .object({
     slug: slugSchema,
-    /** P6.7.5 — internal editor label. Defaults to title if omitted. */
-    name: z.string().min(1).max(256).optional(),
     title: z.string().min(1).max(256),
+    /**
+     * #1142 — the page's public label in breadcrumbs, navigation and the
+     * page picker ("Pricing" for "Pricing for teams of every size").
+     * Omitted = the create-time resolver stores `title` (stored data).
+     */
+    shortTitle: pageShortTitleSchema.optional(),
     /**
      * P6.7.6 — optional. When omitted, the handler resolves to
      * `site_defaults.default_template_id` at create time. Stored data,
@@ -568,6 +693,16 @@ export const pageCreateSchema = z
      * becomes "<parent's path>/<slug>". Omit (or null) for a top-level page.
      */
     parentPageId: z.string().uuid().nullable().optional(),
+    /**
+     * Epic #1107 — what the page IS (page type slug). Omit to take the type
+     * whose `templates` contain the template; with neither `pageType` nor
+     * `templateId`, the site's default page type and its default template.
+     */
+    pageType: pageTypeSlugSchema.optional(),
+    /** Property values, validated against the page type. */
+    properties: z.record(z.string(), z.unknown()).optional(),
+    /** Terms (`caelo:term/<listId>/<itemId>`) from the page type's vocabularies. */
+    terms: z.array(z.string().max(120)).max(100).optional(),
   })
   .strict();
 
@@ -602,9 +737,9 @@ export const pageUpdateSchema = z
      * Routes that load the page first should always pass it back.
      */
     expectedVersion: z.number().int().nonnegative().optional(),
-    /** P6.7.5 — three independently-editable identifiers. */
-    name: z.string().min(1).max(256).optional(),
     title: z.string().min(1).max(256).optional(),
+    /** #1142 — the breadcrumb / navigation label; see {@link pageCreateSchema}. */
+    shortTitle: pageShortTitleSchema.optional(),
     slug: slugSchema.optional(),
     templateId: z.string().uuid().optional(),
     status: pageStatusSchema.optional(),
@@ -620,6 +755,16 @@ export const pageUpdateSchema = z
      * every inbound link, which is never a safe default (CLAUDE.md §2).
      */
     redirectFromOld: z.enum(["auto", "skip"]).optional(),
+    /**
+     * Epic #1107 — switch the page type (slug). The template must be one of
+     * the type's templates (pass `templateId` too when it is not), and the
+     * page's properties and terms must fit the new type.
+     */
+    pageType: pageTypeSlugSchema.optional(),
+    /** Merged into the page's properties; `null` removes a property. */
+    properties: z.record(z.string(), z.unknown()).optional(),
+    /** Replaces the page's terms (`caelo:term/<listId>/<itemId>`). */
+    terms: z.array(z.string().max(120)).max(100).optional(),
   })
   .strict();
 
@@ -669,10 +814,10 @@ const contentValuesSchema = z.record(z.string(), z.unknown());
 
 /**
  * v0.12.0 — why this row exists as a shared/reusable instance.
- * Surfaced in the `## Content Library` system-prompt block so the AI
- * can decide *reuse the synced row* vs *fork to unsynced* vs *mint
- * new* without a tool round-trip. Required by the AI's
- * create_content_instance tool description; legacy callers may pass
+ * Shown by the AI's list_content_instances tool so the AI can decide
+ * *reuse the synced row* vs *fork to unsynced* vs *mint new* without
+ * asking the operator. Required by the AI's
+ * create_content_instances tool description; legacy callers may pass
  * null (the migration-0093 unsynced rows have purpose=NULL).
  * See CLAUDE.md §1A.
  */

package/src/css-scope-scan.ts

@@ -7,7 +7,7 @@
  * that is not tied to the module bleeds into every other module on the
  * page: an `h1 {}` in the hero restyles the pricing table's heading, a
  * `.card {}` in one module restyles another module's cards. The
- * convention (edit_module description, design-quality skill) is to nest
+ * convention (update_modules_many description, design-quality skill) is to nest
  * module CSS under the module's own root class; this scanner is the
  * mechanical write-time check that rides the authoring tool's result,
  * so the AI fixes the selector in the same turn. A warning, not a gate: