@caelo-cms/shared 0.11.0 → 0.11.1

package/src/ai-tools.ts

@@ -17,15 +17,14 @@ import {
   contentInstanceDeleteSchema,
   contentInstanceUpdateSchema,
   forkPlacementContentSchema,
-  MODULE_CSS_MAX,
-  MODULE_HTML_MAX,
-  MODULE_JS_MAX,
   type ModuleField,
   moduleFieldSchema,
+  pageShortTitleSchema,
   pageTypeSlugSchema,
   setPlacementContentSchema,
   slugSchema,
 } from "./content.js";
+import type { SourceLanguage } from "./escaped-line-breaks.js";
 import { LIST_ITEM_ATTR_RE } from "./lists/item-attr.js";
 import { pluginPreviewSelectionSchema } from "./plugin-preview.js";
 import { redirectTargetPathSchema } from "./redirect-target.js";
@@ -71,9 +70,10 @@ function stripSurroundingQuotes(v: unknown): unknown {
  * is handled in one place instead of refused per tool.
  *
  * @param schema - the string schema (length caps, min) the decoded value must satisfy.
+ * @param language - the grammar of the value (`html`, `css`, `js`).
  */
-export function sourceTextArg<T extends z.ZodType<string>>(schema: T) {
-  return z.preprocess(decodeSourceTextTransport, schema);
+export function sourceTextArg<T extends z.ZodType<string>>(schema: T, language: SourceLanguage) {
+  return z.preprocess((value) => decodeSourceTextTransport(value, language), schema);
 }
 
 export const positionInputSchema = z.preprocess(
@@ -87,63 +87,6 @@ export const positionInputSchema = z.preprocess(
   ]),
 );
 
-export const editModuleToolInput = z
-  .object({
-    moduleId: z.string().uuid(),
-    displayName: z.string().min(1).max(128).optional(),
-    /**
-     * v0.12.0 — rewrite the module's purpose. Optional; passing it
-     * updates the `list_modules` catalog your future self will read.
-     */
-    description: z.string().max(1000).optional(),
-    /** v0.12.0 — re-classify the module's role tag. */
-    kind: z.enum(["chrome", "hero", "content", "cta", "utility"]).optional(),
-    /**
-     * v0.12.3 (issue #106) — re-classify the module's stable `type` (the
-     * class a parent's `allowedModuleTypes` whitelist matches against,
-     * e.g. `button`). Rarely needed; usually derived from displayName at
-     * create time. Set it to make this module satisfy a parent's allowlist.
-     */
-    type: slugSchema.optional(),
-    html: sourceTextArg(z.string().max(MODULE_HTML_MAX)).optional(),
-    css: sourceTextArg(z.string().max(MODULE_CSS_MAX)).optional(),
-    js: sourceTextArg(z.string().max(MODULE_JS_MAX)).optional(),
-    /**
-     * v0.4.0 — module field schema. Each field declares one substitution
-     * slot referenced in the module HTML as `{{name}}`. Page placements
-     * fill these via `set_page_module_content`. Optional on edits — pass
-     * to replace the declared schema.
-     */
-    fields: z.array(moduleFieldSchema).max(64).optional(),
-    /** issue #164 slice 2 — see addModuleToolInput.bindThemeLiterals. */
-    bindThemeLiterals: z.boolean().optional(),
-  })
-  .strict()
-  // e2e-livedit run 40351690739: a call with only a (placeholder)
-  // moduleId reached the op and came back as a bare "module not found".
-  // An edit that changes nothing is refused before any lookup, with the
-  // fields that make it one.
-  .refine((v) => Object.keys(v).some((k) => k !== "moduleId" && k !== "bindThemeLiterals"), {
-    message:
-      "edit_module changes nothing: pass what to change (html, css, js, fields, displayName, description, kind or type). list_modules shows the modules; add_module creates a new one.",
-  });
-
-/**
- * v0.4.0 — `set_page_module_content` AI tool. Fills the content values for
- * a module placement on a specific page. Page-bound + branch-isolated per
- * chat until publish (unlike `edit_module` which is global + immediate).
- */
-export const setPageModuleContentToolInput = z
-  .object({
-    pageId: z.string().uuid(),
-    blockName: z.string().min(1).max(64),
-    position: z.number().int().nonnegative(),
-    /** Map of module field name → value. Fully replaces existing values. */
-    contentValues: z.record(z.string(), z.unknown()),
-  })
-  .strict();
-export type SetPageModuleContentToolInput = z.infer<typeof setPageModuleContentToolInput>;
-
 export const siteMemoryProposeToolInput = z
   .object({
     slot: z.enum(["purpose", "brand-voice", "tone", "banned-phrases", "instructions", "glossary"]),
@@ -218,9 +161,9 @@ export const addModuleToolInput = z
     description: z.string().max(1000).optional(),
     kind: z.enum(["chrome", "hero", "content", "cta", "utility"]).optional(),
     type: slugSchema.optional(),
-    html: sourceTextArg(z.string().min(1).max(50_000)).optional(),
-    css: sourceTextArg(z.string().max(50_000)).optional(),
-    js: sourceTextArg(z.string().max(50_000)).optional(),
+    html: sourceTextArg(z.string().min(1).max(50_000), "html").optional(),
+    css: sourceTextArg(z.string().max(50_000), "css").optional(),
+    js: sourceTextArg(z.string().max(50_000), "js").optional(),
     fields: z.array(moduleFieldSchema).max(64).optional(),
     bindThemeLiterals: z.boolean().optional(),
     /**
@@ -233,8 +176,8 @@ export const addModuleToolInput = z
      * stores the values as the minted module's `fields[].default` —
      * which requires explicit `fields` (moduleize field names are
      * unknowable up front) and is rejected for `moduleId` reuse (a
-     * shared module renders its stored defaults; edit_module changes
-     * them).
+     * shared module renders its stored defaults; update_modules_many
+     * changes them).
      */
     values: z.record(z.string(), z.unknown()).optional(),
   })
@@ -245,7 +188,7 @@ export const addModuleToolInput = z
         ctx.addIssue({
           code: z.ZodIssueCode.custom,
           message:
-            "Reusing a module on a layout renders the module's STORED field defaults — `values` has nothing to bind to. Drop `values` (the chrome shows the module as-is), or change the shared copy via edit_module.",
+            "Reusing a module on a layout renders the module's STORED field defaults — `values` has nothing to bind to. Drop `values` (the chrome shows the module as-is), or change the shared copy via update_modules_many.",
         });
       } else if (input.fields === undefined || input.fields.length === 0) {
         ctx.addIssue({
@@ -269,7 +212,7 @@ export const addModuleToolInput = z
     // (§1A/§11), so we do NOT reject a moduleId call that also carries authoring
     // fields. Those fields are not applied here; the tool HANDLER surfaces an
     // INFO for any ignored field whose value DIFFERS from the module's stored
-    // one, pointing at edit_module — so a dropped change is never silent (§2).
+    // one, pointing at update_modules_many — so a dropped change is never silent (§2).
     if (input.moduleId !== undefined) return;
     if (input.displayName === undefined || input.html === undefined) {
       ctx.addIssue({
@@ -361,44 +304,6 @@ export const deleteContentInstanceToolInput = contentInstanceDeleteSchema;
 export const setPlacementContentToolInput = setPlacementContentSchema;
 export const forkPlacementContentToolInput = forkPlacementContentSchema;
 
-export const AI_TOOLS = [
-  "edit_module",
-  "site_memory_propose",
-  "add_module",
-  "create_page",
-  // audit #3 — page metadata (name/title/slug/template/status) is one tool for
-  // 1..200 pages: `update_pages_many`. The former rename_page / set_page_title
-  // / change_page_slug were single-field wrappers over the same pages.update.
-  "update_pages_many",
-  // audit #4 — one delete tool for 1..200 pages, disposition per page.
-  // The former singular delete_page folded in (n=1 is a one-item array).
-  "delete_pages_many",
-  // one remove-module tool routed by target (page|layout).
-  "remove_module_from",
-  "update_theme",
-  "set_template_layout",
-  "create_layout",
-  "set_site_defaults",
-  "duplicate_page",
-  "repoint_page_template",
-  "move_module",
-  "reorder_module",
-  "set_nav_menu",
-  "add_plugin_to_page",
-  // v0.12.0 — content_instances + placement binding
-  "list_content_instances",
-  "get_content_instance",
-  "create_content_instance",
-  "set_content_instance_values",
-  "delete_content_instance",
-  "set_placement_content",
-  "fork_placement_content",
-  // issue #299 — bulk-first build path (§11)
-  "build_page",
-  "create_content_instances",
-  "set_page_module_content_many",
-] as const;
-export type AiToolName = (typeof AI_TOOLS)[number];
 export type AddPluginToPageToolInput = z.infer<typeof addPluginToPageToolInput>;
 export type ListContentInstancesToolInput = z.infer<typeof listContentInstancesToolInput>;
 export type GetContentInstanceToolInput = z.infer<typeof getContentInstanceToolInput>;
@@ -473,7 +378,7 @@ export const CHAT_MAX_ATTACHMENTS = 4;
  * `position` / `field` (#917) — plus `item` / `key` for an entry of a
  * local list field (epic #1107) — name the placement field the text
  * comes from when the preview marked it, so the AI can address it in
- * `set_page_module_content` without inspecting the page first.
+ * `set_page_module_content_many` without inspecting the page first.
  * `listItem` is the `data-caelo-list-item` of the list entry the element
  * sits in (epic #1107, `docs/lists.md` §13): the chip then names that
  * entry — of a shared list, or of a module's own list — not just the
@@ -676,8 +581,8 @@ export const createTemplateToolInput = z
   .object({
     slug: slugInputSchema,
     displayName: z.string().min(1).max(256),
-    html: sourceTextArg(z.string().min(1).max(2_000_000)),
-    css: sourceTextArg(z.string().max(2_000_000)).default(""),
+    html: sourceTextArg(z.string().min(1).max(2_000_000), "html"),
+    css: sourceTextArg(z.string().max(2_000_000), "css").default(""),
     layoutId: z.string().uuid().optional(),
     /** Epic #1107 — the page type (slug) this template serves; omit for the site default. */
     pageType: pageTypeSlugSchema.optional(),
@@ -728,8 +633,8 @@ export const createLayoutToolInput = z
   .object({
     slug: slugInputSchema,
     displayName: z.string().min(1).max(200),
-    html: sourceTextArg(z.string().min(1).max(50_000)),
-    css: sourceTextArg(z.string().max(50_000)).optional(),
+    html: sourceTextArg(z.string().min(1).max(50_000), "html"),
+    css: sourceTextArg(z.string().max(50_000), "css").optional(),
     blocks: z
       .array(
         z
@@ -765,8 +670,9 @@ export const duplicatePageToolInput = z
   .object({
     sourcePageId: z.string().uuid(),
     newSlug: slugInputSchema,
-    newName: z.string().min(1).max(256).optional(),
     newTitle: z.string().min(1).max(256).optional(),
+    /** #1142 — the copy's breadcrumb label; omitted = newTitle when given, else the source's. */
+    newShortTitle: pageShortTitleSchema.optional(),
     targetTemplateId: z.string().uuid().optional(),
     /** Where the copy sits: a parent page id, or null for the top level.
      *  Omitted = next to the source (same parent). */
@@ -794,32 +700,40 @@ export const repointPageTemplateToolInput = z
   })
   .strict();
 
-export const moveModuleToolInput = z
-  .object({
-    pageId: z.string().uuid(),
-    moduleId: z.string().uuid(),
-    toBlockName: z.string().min(1).max(80),
-    /** "top" | "bottom" | a 0-based index inside the destination block. */
-    position: positionInputSchema,
-  })
-  .strict();
+/**
+ * `move_module` position: `top` | `bottom` | a 0-based index in the target
+ * block, plus `up` / `down` (one slot within the module's CURRENT block).
+ * Same quote-stripping + numeric-string coercion as `positionInputSchema`.
+ */
+export const movePositionInputSchema = z.preprocess(
+  stripSurroundingQuotes,
+  z.union([
+    z.enum(["top", "bottom", "up", "down"]),
+    z.preprocess(
+      (v) => (typeof v === "string" && /^\d+$/.test(v) ? Number.parseInt(v, 10) : v),
+      z.number().int().min(0).max(1000),
+    ),
+  ]),
+);
 
-export const reorderModuleToolInput = z
+/**
+ * `move_module` — moves a placement to `toBlockName` (omitted = the block it
+ * is in now, i.e. a reorder) at `position`. `up` / `down` only make sense
+ * inside the current block; the handler refuses them with another block.
+ */
+export const moveModuleToolInput = z
   .object({
     pageId: z.string().uuid(),
     moduleId: z.string().uuid(),
-    /**
-     * `up` / `down` shift one slot. An integer is an absolute 0-based
-     * target position within the same block.
-     */
-    direction: z.union([z.enum(["up", "down"]), z.number().int().min(0).max(1000)]),
+    toBlockName: z.string().min(1).max(80).optional(),
+    position: movePositionInputSchema,
   })
   .strict();
 
 /**
  * P7 — `find_media`. Searches the media library by alt-text /
  * filename / mime. Each row carries the media UUID (what
- * `set_theme_asset` / `set_media_alt` require) plus a pre-resolved
+ * `set_theme_asset` / `set_media_alt_many` require) plus a pre-resolved
  * variant URL. The AI's only media-inventory surface — the `## Media`
  * system-prompt block was removed by the context diet (#300), so every
  * asset lookup ("an image of a sunlit office") goes through this tool.
@@ -864,7 +778,7 @@ export const regenerateMediaVariantsToolInput = z
 export type RegenerateMediaVariantsToolInput = z.infer<typeof regenerateMediaVariantsToolInput>;
 
 /**
- * P7 — `set_media_alt`. AI may improve a11y on an existing asset
+ * P7 — one item of `set_media_alt_many`. AI may improve a11y on an existing asset
  * without a human round-trip (e.g. when the editor uploaded an image
  * with the default alt and the AI reads its content). Updates only
  * the alt field on `media_assets`.
@@ -894,7 +808,7 @@ export const setNotFoundPageToolInput = z.object({ pageId: z.string().uuid().nul
 export type SetNotFoundPageToolInput = z.infer<typeof setNotFoundPageToolInput>;
 
 /**
- * 0181 — `set_media_source`. AI records an asset's provenance (source
+ * 0181 — one item of `set_media_source_many`. AI records an asset's provenance (source
  * kind + origin detail) and licence when known. All fields but the
  * assetId are optional; the op COALESCEs so omitted fields stay
  * unchanged.
@@ -910,7 +824,7 @@ export const setMediaSourceToolInput = z
 export type SetMediaSourceToolInput = z.infer<typeof setMediaSourceToolInput>;
 
 /**
- * P8 — `set_page_seo`. Manual / panel writes to the per-page SEO
+ * P8 — one item of `set_page_seo_many`. Manual / panel writes to the per-page SEO
  * sidecar. AI calls this only on explicit user intent
  * ("set the home meta description to ..."). Doesn't bump fingerprints
  * (autofilled_at / optimized_at).
@@ -931,7 +845,7 @@ export const setPageSeoToolInput = z
 export type SetPageSeoToolInput = z.infer<typeof setPageSeoToolInput>;
 
 /**
- * P8 — `autofill_page_seo` (and, per item, `autofill_page_seo_many`).
+ * P8 — one item of `autofill_page_seo_many`.
  * Fill-once. Refuses when the page's SEO was already autofilled. The AI
  * calls it before a page's first Stage; staging and production builds
  * refuse pages without a meta description (deploy/missing-seo.ts).
@@ -945,22 +859,6 @@ export const autofillPageSeoToolInput = z
   .strict();
 export type AutofillPageSeoToolInput = z.infer<typeof autofillPageSeoToolInput>;
 
-/**
- * P8 — `optimize_page_seo`. Explicit re-optimization. Always allowed.
- * Takes optional context (keyword analysis / intent shifts / branding
- * changes). The AI can call this across N pages in one chat turn —
- * the resulting changes batch into one Publish-pill confirm.
- */
-export const optimizePageSeoToolInput = z
-  .object({
-    pageId: z.string().uuid(),
-    metaDescription: z.string().min(1).max(320),
-    ogImageAssetId: z.string().uuid().nullable().optional(),
-    context: z.string().max(4000).optional(),
-  })
-  .strict();
-export type OptimizePageSeoToolInput = z.infer<typeof optimizePageSeoToolInput>;
-
 /**
  * P8 AI-first review pass — bulk variants. Per CLAUDE.md §11, bulk
  * tools save round-trips when the AI knows it has N changes to make
@@ -980,7 +878,7 @@ export type FindRedirectsToolInput = z.infer<typeof findRedirectsToolInput>;
 
 export const bulkCreateRedirectsToolInput = z
   .object({
-    redirects: z
+    items: z
       .array(
         z
           .object({
@@ -1032,7 +930,7 @@ export type BulkDeleteRedirectsToolInput = z.infer<typeof bulkDeleteRedirectsToo
 
 export const bulkOptimizeSeoToolInput = z
   .object({
-    updates: z
+    items: z
       .array(
         z
           .object({
@@ -1049,7 +947,6 @@ export const bulkOptimizeSeoToolInput = z
   .strict();
 export type BulkOptimizeSeoToolInput = z.infer<typeof bulkOptimizeSeoToolInput>;
 
-export type EditModuleToolInput = z.infer<typeof editModuleToolInput>;
 export type SiteMemoryProposeToolInput = z.infer<typeof siteMemoryProposeToolInput>;
 export type CreateTemplateToolInput = z.infer<typeof createTemplateToolInput>;
 // v0.10.22 — `UpdateThemeToolInput` removed alongside `update_theme` tool.
@@ -1067,7 +964,6 @@ export type SetSiteDefaultsToolInput = z.infer<typeof setSiteDefaultsToolInput>;
 export type DuplicatePageToolInput = z.infer<typeof duplicatePageToolInput>;
 export type RepointPageTemplateToolInput = z.infer<typeof repointPageTemplateToolInput>;
 export type MoveModuleToolInput = z.infer<typeof moveModuleToolInput>;
-export type ReorderModuleToolInput = z.infer<typeof reorderModuleToolInput>;
 // v0.10.22 — `SetNavMenuToolInput` removed alongside `set_nav_menu` tool.
 
 /**

package/src/bug-intake.test.ts

@@ -32,7 +32,7 @@ describe("computeBugFingerprint", () => {
   });
 
   it("keeps different tools and different quoted field names apart", async () => {
-    expect(await auto("boom", "build_page")).not.toBe(await auto("boom", "edit_module"));
+    expect(await auto("boom", "build_page")).not.toBe(await auto("boom", "update_modules_many"));
     expect(await auto('Invalid input at "page.slug"')).not.toBe(
       await auto('Invalid input at "page.title"'),
     );

package/src/build-page.ts

@@ -43,10 +43,10 @@ const contentValuesSchema = z.record(z.string(), z.unknown());
  * existing content paths so build_page adds NO new semantics, only batching:
  *
  *   - `inline`   → mint a private (unsynced) content_instance carrying
- *     `values`, exactly what `set_page_module_content` produces for a
+ *     `values`, exactly what `set_page_module_content_many` produces for a
  *     fresh placement.
  *   - `shared`   → mint a reusable content_instance (purpose required —
- *     same decision-support contract as `create_content_instance`) and
+ *     same decision-support contract as `create_content_instances`) and
  *     bind this placement to it, `synced` by default.
  *   - `existing` → bind an already-minted content_instance (reuse-first
  *     per CLAUDE.md §1A) — the batched form of `set_placement_content`.
@@ -94,7 +94,7 @@ export type BuildPageContent = z.infer<typeof buildPageContentSchema>;
  *     extra authoring keys are TOLERATED (§1A/§11 — a placement that can
  *     succeed must not fail over an extra field) but NOT applied; the op
  *     surfaces an info naming any carried field whose value differs from the
- *     module's stored one, pointing at edit_module (§2 — no silent drop).
+ *     module's stored one, pointing at update_modules_many (§2 — no silent drop).
  *
  * The element-level superRefine reports issues WITH the element's array
  * index in the Zod path, so a mode error fails as `modules[3]: …`.
@@ -159,9 +159,9 @@ export const buildPageModuleSchema = z
     description: z.string().max(1000).optional(),
     kind: moduleKindSchema.optional(),
     type: slugSchema.optional(),
-    html: sourceTextArg(z.string().min(1).max(MODULE_HTML_MAX)).optional(),
-    css: sourceTextArg(z.string().max(MODULE_CSS_MAX)).optional(),
-    js: sourceTextArg(z.string().max(MODULE_JS_MAX)).optional(),
+    html: sourceTextArg(z.string().min(1).max(MODULE_HTML_MAX), "html").optional(),
+    css: sourceTextArg(z.string().max(MODULE_CSS_MAX), "css").optional(),
+    js: sourceTextArg(z.string().max(MODULE_JS_MAX), "js").optional(),
     fields: z.array(moduleFieldSchema).max(64).optional(),
     /** issue #164 slice 2 — opt-in mechanical token binding (tool layer). */
     bindThemeLiterals: z.boolean().optional(),
@@ -192,7 +192,7 @@ export const buildPageModuleSchema = z
     // (build_page places; it does not re-author a shared module). To avoid a
     // SILENT dropped change (§2), the HANDLER surfaces an INFO in the result
     // naming any ignored authoring field whose value DIFFERS from the module's
-    // stored one, and points at edit_module. The schema can't do that check (no
+    // stored one, and points at update_modules_many. The schema can't do that check (no
     // DB), so it just allows the entry through.
     if (entry.moduleId !== undefined) return;
     if (entry.displayName === undefined || entry.html === undefined) {
@@ -220,7 +220,7 @@ export const buildPageTargetSchema = z
     pageId: z.string().uuid().optional(),
     slug: slugSchema.optional(),
     title: z.string().min(1).max(256).optional(),
-    name: z.string().min(1).max(256).optional(),
+    shortTitle: pageCreateSchema.shape.shortTitle,
     templateId: z.string().uuid().optional(),
     status: pageStatusSchema.optional(),
     /**
@@ -268,7 +268,7 @@ export const buildPageTargetSchema = z
       [
         "slug",
         "title",
-        "name",
+        "shortTitle",
         "templateId",
         "status",
         "parentPageId",

package/src/content.test.ts

@@ -91,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{} /*]]>*/",

package/src/content.ts

@@ -11,6 +11,7 @@
  */
 
 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";
@@ -126,14 +127,34 @@ export function htmlEscapedMarkupMessage(field: string, value: string): string |
   return `${field} is HTML-escaped (&lt;…&gt; instead of <…>) — send the markup itself, unescaped.`;
 }
 
-const noCorruptMarkup = (field: string) => (value: string, ctx: z.RefinementCtx) => {
-  const message = jsonEncodedCodeMessage(field, value) ?? htmlEscapedMarkupMessage(field, value);
+/**
+ * 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()
@@ -168,7 +189,7 @@ const moduleCss = z
   .string()
   .max(MODULE_CSS_MAX, `css exceeds ${MODULE_CSS_MAX} bytes`)
   .refine(noCdata, cdataMessage("css"))
-  .superRefine(noJsonEncodedCode("css"));
+  .superRefine(noCorruptCss);
 const moduleJs = z
   .string()
   .max(MODULE_JS_MAX, `js exceeds ${MODULE_JS_MAX} bytes`)
@@ -276,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.
@@ -491,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);
@@ -627,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
@@ -636,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,
@@ -703,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(),
@@ -780,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: