@caelo-cms/shared 0.10.24 → 0.10.27

package/src/content.test.ts

@@ -2,9 +2,9 @@
 
 import { describe, expect, it } from "bun:test";
 import {
-  localeSchema,
   MODULE_HTML_MAX,
   moduleCreateSchema,
+  moduleUpdateSchema,
   pageCreateSchema,
   pageSetModulesSchema,
   pageUpdateSchema,
@@ -29,21 +29,6 @@ describe("slugSchema", () => {
   });
 });
 
-describe("localeSchema", () => {
-  it("accepts language and language-region", () => {
-    expect(localeSchema.safeParse("en").success).toBe(true);
-    expect(localeSchema.safeParse("de").success).toBe(true);
-    expect(localeSchema.safeParse("de-AT").success).toBe(true);
-  });
-
-  it("rejects malformed locales", () => {
-    expect(localeSchema.safeParse("EN").success).toBe(false);
-    expect(localeSchema.safeParse("en-us").success).toBe(false);
-    expect(localeSchema.safeParse("eng").success).toBe(false);
-    expect(localeSchema.safeParse("").success).toBe(false);
-  });
-});
-
 describe("moduleCreateSchema", () => {
   it("accepts a minimal module", () => {
     const r = moduleCreateSchema.safeParse({
@@ -73,6 +58,104 @@ describe("moduleCreateSchema", () => {
     });
     expect(r.success).toBe(false);
   });
+
+  // issue #432 — CDATA wrappers stored verbatim broke rendering and sent the
+  // AI into a ~20-loop visual repair spiral; the write boundary now rejects
+  // them with an actionable message.
+  it("rejects XML CDATA wrappers in css and js, with an actionable message", () => {
+    const base = { slug: "site-header", displayName: "Site header", html: "<header></header>" };
+    const css = moduleCreateSchema.safeParse({
+      ...base,
+      css: "/*<![CDATA[*/ .x { color: red } /*]]>*/",
+    });
+    expect(css.success).toBe(false);
+    if (!css.success) {
+      expect(css.error.issues.map((i) => i.message).join(" ")).toContain("CDATA");
+    }
+    const js = moduleCreateSchema.safeParse({
+      ...base,
+      js: "//<![CDATA[\nconsole.log('hi');\n//]]>",
+    });
+    expect(js.success).toBe(false);
+  });
+
+  it("accepts plain css/js (and js merely mentioning ']]>' in a string)", () => {
+    const base = { slug: "site-header", displayName: "Site header", html: "<header></header>" };
+    expect(
+      moduleCreateSchema.safeParse({ ...base, css: ".x { color: red }", js: "console.log(1);" })
+        .success,
+    ).toBe(true);
+    // Only the OPENING marker is the corruption signature; a bare "]]>"
+    // inside a string literal is legitimate (e.g. code emitting XML).
+    expect(moduleCreateSchema.safeParse({ ...base, js: 'xml += "]]>";' }).success).toBe(true);
+  });
+
+  it("rejects CDATA on the update path too (edit_module / edit_content funnel)", () => {
+    const r = moduleUpdateSchema.safeParse({
+      moduleId: "8c2f2f2a-0000-4000-8000-000000000432",
+      css: "/*<![CDATA[*/ .x{} /*]]>*/",
+    });
+    expect(r.success).toBe(false);
+  });
+});
+
+// CLAUDE.md §1A / issue #417 — repeating content is a list field, never
+// numbered scalars. Threshold is 3: a pair (col1/col2) is a legitimate
+// layout split; three-or-more numbered siblings is a list.
+describe("moduleFields numbered-scalar fanout guard (§1A)", () => {
+  const mod = (fields: unknown) =>
+    moduleCreateSchema.safeParse({
+      slug: "cards",
+      displayName: "Cards",
+      html: "<div></div>",
+      fields,
+    });
+  const text = (name: string) => ({ name, kind: "text", label: name });
+
+  it("rejects a bare base + numbered siblings (label, label2, label3)", () => {
+    const r = mod([text("label"), text("label2"), text("label3")]);
+    expect(r.success).toBe(false);
+    if (!r.success) {
+      const msg = r.error.issues[0]?.message ?? "";
+      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("module-list");
+      expect(msg).toContain("§1A");
+    }
+  });
+
+  it("rejects underscore-separated runs (quote_1..quote_3) and mixed separators", () => {
+    expect(mod([text("quote_1"), text("quote_2"), text("quote_3")]).success).toBe(false);
+    expect(mod([text("logo1"), text("logo_2"), text("logo_3")]).success).toBe(false);
+  });
+
+  it("rejects fanout on moduleUpdateSchema too (same shared fields array)", () => {
+    const r = moduleUpdateSchema.safeParse({
+      moduleId: "6f9619ff-8b86-4d01-b42d-00cf4fc964ff",
+      fields: [text("card1"), text("card2"), text("card3")],
+    });
+    expect(r.success).toBe(false);
+  });
+
+  it("allows a two-field split (col1/col2) — threshold is 3", () => {
+    expect(mod([text("col1"), text("col2")]).success).toBe(true);
+    expect(mod([text("label"), text("label2")]).success).toBe(true);
+    expect(mod([text("address_line1"), text("address_line2")]).success).toBe(true);
+  });
+
+  it("allows unrelated numbered fields that never form a run of 3", () => {
+    expect(mod([text("hero_title"), text("cta_2024"), text("step_1")]).success).toBe(true);
+    // Same suffix, different bases — no shared run.
+    expect(mod([text("left_col1"), text("right_col1"), text("mid_col1")]).success).toBe(true);
+  });
+
+  it("scopes to scalar kinds — numbered list fields are a modelling question, not fanout", () => {
+    const linkList = (name: string) => ({ name, kind: "link-list", label: name });
+    expect(mod([linkList("links1"), linkList("links2"), linkList("links3")]).success).toBe(true);
+  });
 });
 
 describe("pageCreateSchema (no raw HTML invariant)", () => {
@@ -84,7 +167,6 @@ describe("pageCreateSchema (no raw HTML invariant)", () => {
     });
     expect(r.success).toBe(true);
     if (!r.success) return;
-    expect(r.data.locale).toBe("en");
     // status is intentionally OPTIONAL (no schema default): pages.create
     // resolves it at write time — published on a bootstrap site, else draft.
     // Omitting it here leaves it undefined for the handler to resolve.

package/src/content.ts

@@ -84,11 +84,6 @@ export function slugifyModuleSection(
   return `${deriveModuleType(displayName)}-${idx}-${suffix}`;
 }
 
-/** BCP-47 shape: 2-letter language with optional 2-letter region. P9 widens this. */
-export const localeSchema = z
-  .string()
-  .regex(/^[a-z]{2}(-[A-Z]{2})?$/, "locale must be 'xx' or 'xx-YY' (BCP-47 shape)");
-
 const displayNameSchema = z.string().min(1).max(128);
 
 /** Caps are arbitrary but cheap — paste-of-binary mistakes get caught. */
@@ -99,8 +94,39 @@ 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`);
-const moduleCss = z.string().max(MODULE_CSS_MAX, `css exceeds ${MODULE_CSS_MAX} bytes`);
-const moduleJs = z.string().max(MODULE_JS_MAX, `js exceeds ${MODULE_JS_MAX} bytes`);
+
+/**
+ * issue #432 root-cause guard — reject XML CDATA wrappers in module css/js.
+ *
+ * Module css/js is stored and served VERBATIM, so a `<![CDATA[ … ]]>`
+ * wrapper (an XHTML-era idiom the AI occasionally reaches for when
+ * "protecting" inline code) reaches the browser unparsed: the stylesheet
+ * fails to apply and the script throws `SyntaxError: Unexpected token '<'`.
+ * On e2e runs 31000584991 / 31000699422 (2026-08-05) exactly this landed
+ * silently, the page rendered broken, and the model burned ~15–20 extra
+ * loops (~+1.2M input tokens) discovering and repairing it via
+ * screenshot/inspect/edit cycles. Rejecting at the write boundary with an
+ * actionable message turns that repair spiral into a single corrected call
+ * (CLAUDE.md §11 — failure surfaces are AI-actionable; §2 — fail loudly).
+ *
+ * css/js only: CDATA is never valid CSS or JS, while an html body may
+ * legitimately carry CDATA inside inline `<svg>`/`<math>` foreign content.
+ */
+const CDATA_OPEN = "<![CDATA[";
+const noCdata = (value: string): boolean => !value.includes(CDATA_OPEN);
+const cdataMessage = (field: "css" | "js"): string =>
+  `${field} contains an XML CDATA marker (${CDATA_OPEN}) — module ${field} is stored and served ` +
+  `verbatim, so CDATA wrappers reach the browser unparsed and break rendering. ` +
+  `Remove the wrapper and resend plain ${field === "css" ? "CSS" : "JavaScript"}.`;
+
+const moduleCss = z
+  .string()
+  .max(MODULE_CSS_MAX, `css exceeds ${MODULE_CSS_MAX} bytes`)
+  .refine(noCdata, cdataMessage("css"));
+const moduleJs = z
+  .string()
+  .max(MODULE_JS_MAX, `js exceeds ${MODULE_JS_MAX} bytes`)
+  .refine(noCdata, cdataMessage("js"));
 
 /**
  * v0.4.0 — module field schema. Each field declares one substitution slot in
@@ -283,6 +309,54 @@ export const moduleRefSchema = z
   .strict();
 export type ModuleRef = z.infer<typeof moduleRefSchema>;
 
+/**
+ * CLAUDE.md §1A — "repeating content is a list field, never numbered
+ * scalars". This guard rejects the mechanically detectable half of that
+ * rule: a RUN of 3+ sibling scalar fields sharing a base name plus a
+ * numeric suffix (`label`, `label2`, `label3` / `quote_1`…`quote_3`).
+ *
+ * Threshold is 3 (issue #417): a two-field split (`col1`/`col2` for a
+ * two-column layout) is routinely a genuine layout role, so a pair stays
+ * legal; three-or-more numbered siblings is repeating content that must
+ * be ONE list field. The bare base name counts as an implicit member of
+ * its run — `label` next to `label2`/`label3` is item 1 in disguise.
+ *
+ * Deliberately out of scope (guidance-only, per the issue): content-
+ * derived names (`quote_justamazing`) and mid-name numbering
+ * (`step1_title`) — neither is detectable without false positives.
+ * Nested/list kinds are excluded too: a numbered run of lists is
+ * already a modelling question, not scalar fanout. The server-side
+ * extractor fallback (`extract-module-structure.ts`) is also
+ * unguarded on purpose: it numbers repeated tags in messy HUMAN-
+ * authored HTML, runs only when the caller declared no fields, and its
+ * output never re-enters this schema — the guard polices the boundary
+ * where the AI (or a human) AUTHORS `fields[]` explicitly.
+ */
+const NUMBERED_SCALAR_FANOUT_THRESHOLD = 3;
+const numberedFieldName = /^([a-z][a-z0-9_]*?)_?\d+$/;
+
+function findNumberedScalarFanoutRuns(
+  fields: readonly { name: string; kind: string }[],
+): string[][] {
+  const scalarKinds = new Set<string>(MODULE_FIELD_PRIMITIVE_KINDS);
+  const scalarNames = fields.filter((f) => scalarKinds.has(f.kind)).map((f) => f.name);
+  const byBase = new Map<string, string[]>();
+  for (const name of scalarNames) {
+    const m = numberedFieldName.exec(name);
+    const base = m?.[1];
+    if (base === undefined) continue;
+    const members = byBase.get(base);
+    if (members) members.push(name);
+    else byBase.set(base, [name]);
+  }
+  const runs: string[][] = [];
+  for (const [base, members] of byBase) {
+    const run = scalarNames.includes(base) ? [base, ...members] : members;
+    if (run.length >= NUMBERED_SCALAR_FANOUT_THRESHOLD) runs.push(run);
+  }
+  return runs;
+}
+
 const moduleFieldsArray = z
   .array(moduleFieldSchema)
   .max(64, "modules may declare at most 64 fields")
@@ -295,6 +369,20 @@ const moduleFieldsArray = z
       }
       seen.add(f.name);
     }
+    for (const run of findNumberedScalarFanoutRuns(arr)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        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 ' +
+          '"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; ' +
+          `${NUMBERED_SCALAR_FANOUT_THRESHOLD}+ numbered siblings is a list.`,
+      });
+    }
   });
 
 /**
@@ -457,7 +545,6 @@ export const pageStatusSchema = z.enum(["draft", "published"]);
 export const pageCreateSchema = z
   .object({
     slug: slugSchema,
-    locale: localeSchema.default("en"),
     /** 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),

package/src/context.ts

@@ -31,6 +31,12 @@ export interface ExecutionContext {
    * fold consecutive AI actions into one entry.
    */
   readonly chatTaskId?: string;
+  /**
+   * For a plugin installed as an external artifact: the digest of the
+   * artifact this call runs. Private storage operations accept the call
+   * only while exactly this artifact is the active, granted one.
+   */
+  readonly pluginArtifactDigest?: string;
   /**
    * P10.5: parent attribution for subagent invocations. When the
    * `spawn_subagent` tool calls runChatTurn for the child, it carries

package/src/font-assets.ts

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: MPL-2.0
+import { z } from "zod";
+
+export const fontRef = z
+  .object({ id: z.string().uuid(), sha256: z.string().regex(/^[a-f0-9]{64}$/) })
+  .strict();
+export const fontLicense = z
+  .object({
+    name: z.string().min(1).max(200),
+    text: z.string().min(1).max(100_000),
+    webEmbedding: z.boolean(),
+    documentEmbedding: z.boolean(),
+  })
+  .strict();
+export const fontMetadata = fontRef.extend({
+  family: z.string(),
+  subfamily: z.string(),
+  postscriptName: z.string(),
+  cssFamily: z.string(),
+  format: z.enum(["ttf", "otf", "woff", "woff2"]),
+  weight: z.number(),
+  style: z.enum(["normal", "italic"]),
+  axes: z.record(z.string(), z.object({ min: z.number(), max: z.number(), default: z.number() })),
+  sizeBytes: z.number(),
+  glyphCount: z.number(),
+  embedding: z.object({
+    web: z.boolean(),
+    document: z.boolean(),
+    subset: z.boolean(),
+    restriction: z.string().nullable(),
+  }),
+  license: fontLicense,
+  source: z.string(),
+  createdAt: z.string(),
+});
+export type FontRef = z.infer<typeof fontRef>;
+export type FontMetadata = z.infer<typeof fontMetadata>;
+export const fontImportInput = z
+  .object({
+    dataBase64: z.string().min(1).max(11_184_812),
+    license: fontLicense,
+    source: z.string().min(1).max(1000),
+  })
+  .strict();
+export const fontResolveInput = fontRef
+  .extend({
+    use: z.enum(["web", "document"]),
+    text: z.string().max(200_000).default(""),
+    formats: z
+      .array(z.enum(["ttf", "otf", "woff", "woff2"]))
+      .min(1)
+      .max(4),
+  })
+  .strict();
+export const fontReadInput = fontRef
+  .extend({ offset: z.number().int().min(0), length: z.number().int().min(1).max(262144) })
+  .strict();
+export const fontFindInput = z
+  .object({
+    query: z.string().max(200).default(""),
+    limit: z.number().int().min(1).max(100).default(50),
+  })
+  .strict();

package/src/google-models.ts

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/** Google image models, curated against https://ai.google.dev/gemini-api/docs/models
+ * on 2026-09-11. Chat models live in admin-core's model-catalog.json; image-only
+ * models stay out of it because they cannot call tools. Exact IDs are
+ * intentional; automatic latest aliases could change behaviour.
+ */
+export const GOOGLE_IMAGE_MODELS = [
+  { id: "gemini-3.1-flash-image", label: "Nano Banana 2 (Gemini 3.1 Flash Image)" },
+  { id: "gemini-3.1-flash-lite-image", label: "Nano Banana 2 Lite" },
+  { id: "gemini-3-pro-image", label: "Nano Banana Pro (Gemini 3 Pro Image)" },
+  { id: "gemini-2.5-flash-image", label: "Nano Banana (Gemini 2.5 Flash Image)" },
+] as const;

package/src/image-capabilities.ts

@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Image model capabilities (#529) and the one check every caller runs
+ * before a paid image request — the chat's generate_image/edit_image
+ * (admin-core) and the plugin `ctx.images` broker (plugin-host) alike.
+ * Profiles per model live in admin-core/src/ai/image-models.ts.
+ */
+
+/** What callers may ask of a model. Reported verbatim to the AI and plugins. */
+export interface ImageCapabilities {
+  readonly provider: "openai" | "google";
+  readonly model: string;
+  /** `edit` = change a source image (optionally under a mask). */
+  readonly operations: readonly ("generate" | "edit")[];
+  readonly references: {
+    readonly max: number;
+    readonly maxBytesEach: number;
+    readonly maxBytesTotal: number;
+    readonly mediaTypes: readonly ("image/png" | "image/jpeg" | "image/webp")[];
+  };
+  /** True when an edit can be limited to a masked region. */
+  readonly mask: boolean;
+  /** Output shapes accepted as `size`. */
+  readonly sizes: readonly ("1024x1024" | "1792x1024" | "1024x1792")[];
+  /** Native resolutions accepted as `imageSize` (empty: not selectable). */
+  readonly imageSizes: readonly ("1K" | "2K" | "4K")[];
+}
+
+/** The fields the check reads — satisfied by ImageCapabilities and by the
+ *  plugin SDK's structurally identical PluginImageCapabilities. */
+export interface ImageCapabilityLimits {
+  readonly model: string;
+  readonly operations: readonly string[];
+  readonly references: {
+    readonly max: number;
+    readonly maxBytesEach: number;
+    readonly maxBytesTotal: number;
+    readonly mediaTypes: readonly string[];
+  };
+  readonly mask: boolean;
+  readonly sizes: readonly string[];
+  readonly imageSizes: readonly string[];
+}
+
+/**
+ * Check a request against a model's capabilities. Returns an AI-actionable
+ * reason, or null when the request fits. Run before any reservation.
+ */
+export function capabilityRefusal(
+  caps: ImageCapabilityLimits,
+  request: {
+    operation: "generate" | "edit";
+    references: readonly { bytes: number; mediaType: string }[];
+    mask: boolean;
+    size?: string;
+    imageSize?: string;
+  },
+): string | null {
+  if (!caps.operations.includes(request.operation)) {
+    return `${caps.model} cannot ${request.operation} images. Supported: ${caps.operations.join(", ")}.`;
+  }
+  if (request.mask && !caps.mask) {
+    return `${caps.model} cannot limit an edit to a mask. Describe the region in the prompt instead, or configure a model that supports masks.`;
+  }
+  if (request.references.length > caps.references.max) {
+    return `${caps.model} accepts at most ${caps.references.max} reference image(s); ${request.references.length} given.`;
+  }
+  let total = 0;
+  for (const ref of request.references) {
+    if (!caps.references.mediaTypes.includes(ref.mediaType)) {
+      return `${caps.model} accepts reference images as ${caps.references.mediaTypes.join(", ")}; got ${ref.mediaType}.`;
+    }
+    if (ref.bytes > caps.references.maxBytesEach) {
+      return `A reference image is larger than ${caps.references.maxBytesEach} bytes, the limit for ${caps.model}.`;
+    }
+    total += ref.bytes;
+  }
+  if (total > caps.references.maxBytesTotal) {
+    return `Reference images total ${total} bytes; ${caps.model} accepts ${caps.references.maxBytesTotal}.`;
+  }
+  if (request.size && !caps.sizes.includes(request.size)) {
+    return `${caps.model} does not produce ${request.size}. Sizes: ${caps.sizes.join(", ")}.`;
+  }
+  if (request.imageSize && !caps.imageSizes.includes(request.imageSize)) {
+    return caps.imageSizes.length === 0
+      ? `${caps.model} has no selectable resolution; omit imageSize.`
+      : `${caps.model} resolutions: ${caps.imageSizes.join(", ")}.`;
+  }
+  return null;
+}

package/src/index.ts

@@ -12,11 +12,12 @@ export * from "./context.js";
 export * from "./css-gradient-scan.js";
 export * from "./css-var-scan.js";
 export * from "./design-draft-shell.js";
-export * from "./design-manifest.js";
+export * from "./font-assets.js";
 export * from "./fonts.js";
 export * from "./genesis.js";
 export * from "./genesis-inventory.js";
-export * from "./i18n.js";
+export * from "./google-models.js";
+export * from "./image-capabilities.js";
 export * from "./interactions.js";
 export {
   type LogContext,
@@ -31,6 +32,7 @@ export {
 } from "./logger.js";
 export * from "./media.js";
 export * from "./page-log.js";
+export * from "./plugin-preview.js";
 export * from "./preview-compose.js";
 export * from "./preview-scanner.js";
 export * from "./proposal-status.js";
@@ -56,4 +58,5 @@ export * from "./theme-ramp.js";
 export * from "./theme-render.js";
 export * from "./themes.js";
 export * from "./themes-errors.js";
+export * from "./url.js";
 export { CAELO_VERSION, CALEO_VERSION, type CaeloVersion, parseVersion } from "./version.js";

package/src/media.ts

@@ -184,6 +184,14 @@ export function extractMediaRefs(html: string): MediaRef[] {
 
 const sha256Schema = z.string().regex(/^[0-9a-f]{64}$/, "must be hex sha256");
 
+/**
+ * #531 — `library` assets are listed and placeable on pages; `reference`
+ * assets exist only to guide image generation/editing: hidden from the
+ * default listing and refused by the static generator on a page.
+ */
+export const mediaVisibilitySchema = z.enum(["library", "reference"]);
+export type MediaVisibility = z.infer<typeof mediaVisibilitySchema>;
+
 export const mediaUploadInputSchema = z
   .object({
     sha256: sha256Schema,
@@ -213,6 +221,10 @@ export const mediaUploadInputSchema = z
     sourceKind: z.enum(["upload", "ai_generated", "imported", "external"]).optional(),
     sourceDetail: z.string().max(2048).optional(),
     license: z.string().max(200).optional(),
+    /** Defaults to `library`; a re-upload of existing content keeps its visibility. */
+    visibility: mediaVisibilitySchema.optional(),
+    /** #528/#532 — the asset this one was made from (an edit). */
+    derivedFromId: z.string().uuid().optional(),
     variants: z
       .array(
         z.object({
@@ -234,6 +246,8 @@ export const mediaListInputSchema = z
     query: z.string().max(256).optional(),
     mime: z.enum(MEDIA_ALLOWED_MIMES).optional(),
     sort: z.enum(["recent", "most_used"]).default("recent"),
+    /** `library` (default) hides reference images; `all` lists both. */
+    visibility: z.enum(["library", "reference", "all"]).default("library"),
     limit: z.number().int().positive().max(200).default(60),
     offset: z.number().int().nonnegative().default(0),
   })
@@ -264,6 +278,15 @@ export const mediaSetSourceInputSchema = z
   .strict();
 export type MediaSetSourceInput = z.infer<typeof mediaSetSourceInputSchema>;
 
+/** media.set_visibility (#531) — move an asset between library and reference. */
+export const mediaSetVisibilityInputSchema = z
+  .object({
+    assetId: z.string().uuid(),
+    visibility: mediaVisibilitySchema,
+  })
+  .strict();
+export type MediaSetVisibilityInput = z.infer<typeof mediaSetVisibilityInputSchema>;
+
 export const mediaDeleteInputSchema = z
   .object({
     assetId: z.string().uuid(),
@@ -279,12 +302,6 @@ export const mediaRecordUsageInputSchema = z
   .strict();
 export type MediaRecordUsageInput = z.infer<typeof mediaRecordUsageInputSchema>;
 
-export const mediaRecentForAiInputSchema = z
-  .object({
-    limit: z.number().int().positive().max(60).default(30),
-  })
-  .strict();
-
 export const mediaSetCdnInputSchema = z
   .object({
     enabled: z.boolean(),

package/src/plugin-preview.test.ts

@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: MPL-2.0
+import { expect, test } from "bun:test";
+import { chatSendMessageInput } from "./ai-tools.js";
+import {
+  PLUGIN_PREVIEW_REFERENCE_MARKER,
+  pluginPreviewDocumentSchema,
+  pluginPreviewSelectionSchema,
+  readPluginPreviewReference,
+} from "./plugin-preview.js";
+
+test("bounded plugin selections retain exact revision and target identity through chat input", () => {
+  const selection = {
+    pluginSlug: "example",
+    id: "page-one-text",
+    label: "Page 1 · Text",
+    reference: {
+      documentId: crypto.randomUUID(),
+      revisionId: crypto.randomUUID(),
+      pageId: crypto.randomUUID(),
+      part: "text",
+    },
+  };
+  const parsed = chatSendMessageInput.parse({
+    chatSessionId: crypto.randomUUID(),
+    content: "Make this shorter",
+    previewSelection: selection,
+  });
+  expect(parsed.previewSelection).toEqual(selection);
+  expect(
+    pluginPreviewSelectionSchema.safeParse({ ...selection, reference: { html: "x".repeat(257) } })
+      .success,
+  ).toBe(false);
+  expect(
+    pluginPreviewSelectionSchema.safeParse({ ...selection, pluginSlug: "../admin" }).success,
+  ).toBe(false);
+  const target = { id: "one", label: "One", reference: { id: "one" } };
+  expect(
+    pluginPreviewDocumentSchema.safeParse({ html: "<p>One</p>", targets: [target, target] })
+      .success,
+  ).toBe(false);
+});
+
+test("transcripts show a reference label without exposing opaque IDs or losing ordinary text", () => {
+  const selection = {
+    id: "text",
+    label: "Page 1 · Text",
+    pluginSlug: "example",
+    reference: { revisionId: "private-revision", part: "text" },
+  };
+  expect(
+    readPluginPreviewReference(
+      "Shorten this" + PLUGIN_PREVIEW_REFERENCE_MARKER + JSON.stringify(selection),
+    ),
+  ).toEqual({ text: "Shorten this", selection });
+  const literal = "Unrelated message" + PLUGIN_PREVIEW_REFERENCE_MARKER + "not JSON";
+  expect(readPluginPreviewReference(literal)).toEqual({ text: literal });
+});
+
+test("viewport context must reference declared targets and document choices have unique identities", () => {
+  const target = { id: "page", label: "Page", reference: { revisionId: "one" } };
+  expect(
+    pluginPreviewDocumentSchema.safeParse({
+      html: "",
+      targets: [target],
+      contextTargetIds: ["missing"],
+    }).success,
+  ).toBe(false);
+  expect(
+    pluginPreviewDocumentSchema.safeParse({
+      html: "",
+      targets: [target],
+      contextTargetIds: ["page"],
+    }).success,
+  ).toBe(true);
+  const doc = { id: "document", label: "Document", url: "/plugins/example/preview?args=%7B%7D" };
+  expect(pluginPreviewDocumentSchema.safeParse({ html: "", documents: [doc, doc] }).success).toBe(
+    false,
+  );
+});