@drawnagency/primitives 0.1.95 → 0.1.96

package/dist/{chunk-QQBBYQYD.js → chunk-CSVGCAIH.js}

@@ -3,7 +3,7 @@ import {
   pluralize,
   stripHtmlToPlainText,
   truncate
-} from "./chunk-ZKGMLLUQ.js";
+} from "./chunk-IFCQWC3G.js";
 import {
   DeleteButton,
   DragHandle,
@@ -52,13 +52,13 @@ import {
 import {
   getSectionSchema
 } from "./chunk-TZQPOR5A.js";
-import {
-  SingleMediaReferenceSchema
-} from "./chunk-RHWWQV3J.js";
 import {
   defineSection,
   getSection
 } from "./chunk-VKAGMEKE.js";
+import {
+  SingleMediaReferenceSchema
+} from "./chunk-RHWWQV3J.js";
 
 // src/components/sections/LinkHeading/index.tsx
 import { Heading1 } from "lucide-react";

package/dist/chunk-EUSWEVOA.js

@@ -0,0 +1,29 @@
+// src/storage/types.ts
+var StorageConflictError = class extends Error {
+  constructor(currentVersion) {
+    super("Draft has been modified since it was loaded");
+    this.currentVersion = currentVersion;
+    this.name = "StorageConflictError";
+  }
+  currentVersion;
+};
+var IDEMPOTENCY_TRAILER = "Idempotency-Key";
+var IDEMPOTENCY_KEY_RE = /^[A-Za-z0-9._:-]{8,200}$/;
+function withIdempotencyTrailer(subject, key) {
+  if (!key) return subject;
+  if (!IDEMPOTENCY_KEY_RE.test(key)) {
+    throw new Error("Invalid idempotency key: expected 8-200 chars of A-Za-z0-9._:-");
+  }
+  return `${subject}
+
+${IDEMPOTENCY_TRAILER}: ${key}`;
+}
+var ASSET_CACHE_CONTROL = "max-age=31536000, immutable";
+
+export {
+  StorageConflictError,
+  IDEMPOTENCY_TRAILER,
+  IDEMPOTENCY_KEY_RE,
+  withIdempotencyTrailer,
+  ASSET_CACHE_CONTROL
+};

package/dist/components/primitives/index.js

@@ -23,8 +23,8 @@ import {
   cn
 } from "../../chunk-7EOSDFS3.js";
 import "../../chunk-YBVK254P.js";
-import "../../chunk-RHWWQV3J.js";
 import "../../chunk-VKAGMEKE.js";
+import "../../chunk-RHWWQV3J.js";
 import "../../chunk-FM4M4Q2W.js";
 import "../../chunk-JSBRDJBE.js";
 

package/dist/components/sections/brand-guide.js

@@ -2,7 +2,7 @@ import {
   ColorItemSchema,
   ColorSpaceSchema,
   brandGuideSectionDefs
-} from "../../chunk-ZKGMLLUQ.js";
+} from "../../chunk-IFCQWC3G.js";
 import "../../chunk-5THS4K5D.js";
 import "../../chunk-DJAJRBPD.js";
 import "../../chunk-CI624HRS.js";
@@ -11,8 +11,8 @@ import "../../chunk-PZJL2S3Z.js";
 import "../../chunk-WDSVHKAH.js";
 import "../../chunk-7EOSDFS3.js";
 import "../../chunk-YBVK254P.js";
-import "../../chunk-RHWWQV3J.js";
 import "../../chunk-VKAGMEKE.js";
+import "../../chunk-RHWWQV3J.js";
 import "../../chunk-FM4M4Q2W.js";
 import "../../chunk-JSBRDJBE.js";
 export {

package/dist/components/sections/register-schemas.js

@@ -1,7 +1,7 @@
 import {
   allSectionDefs
-} from "../../chunk-QQBBYQYD.js";
-import "../../chunk-ZKGMLLUQ.js";
+} from "../../chunk-CSVGCAIH.js";
+import "../../chunk-IFCQWC3G.js";
 import "../../chunk-YUUUCDXN.js";
 import "../../chunk-5THS4K5D.js";
 import "../../chunk-RQPHPAT2.js";
@@ -16,11 +16,11 @@ import "../../chunk-53DKVAB6.js";
 import "../../chunk-7EOSDFS3.js";
 import "../../chunk-YBVK254P.js";
 import "../../chunk-TZQPOR5A.js";
-import "../../chunk-RHWWQV3J.js";
 import {
   registerRichText,
   registerSchema
 } from "../../chunk-VKAGMEKE.js";
+import "../../chunk-RHWWQV3J.js";
 import "../../chunk-FM4M4Q2W.js";
 import "../../chunk-NSCT3AMV.js";
 import "../../chunk-JSBRDJBE.js";

package/dist/components/sections/register.js

@@ -1,7 +1,7 @@
 import {
   allSectionDefs
-} from "../../chunk-QQBBYQYD.js";
-import "../../chunk-ZKGMLLUQ.js";
+} from "../../chunk-CSVGCAIH.js";
+import "../../chunk-IFCQWC3G.js";
 import "../../chunk-YUUUCDXN.js";
 import "../../chunk-5THS4K5D.js";
 import "../../chunk-RQPHPAT2.js";
@@ -16,10 +16,10 @@ import "../../chunk-53DKVAB6.js";
 import "../../chunk-7EOSDFS3.js";
 import "../../chunk-YBVK254P.js";
 import "../../chunk-TZQPOR5A.js";
-import "../../chunk-RHWWQV3J.js";
 import {
   registerSection
 } from "../../chunk-VKAGMEKE.js";
+import "../../chunk-RHWWQV3J.js";
 import "../../chunk-FM4M4Q2W.js";
 import "../../chunk-NSCT3AMV.js";
 import "../../chunk-JSBRDJBE.js";

package/dist/index.js

@@ -1,21 +1,14 @@
 import {
   ASSET_CACHE_CONTROL,
-  StorageConflictError
-} from "./chunk-VAOW4WXQ.js";
+  IDEMPOTENCY_KEY_RE,
+  IDEMPOTENCY_TRAILER,
+  StorageConflictError,
+  withIdempotencyTrailer
+} from "./chunk-EUSWEVOA.js";
 import {
-  AUDIENCE_COOKIE,
-  AUDIENCE_MAX_AGE_SECONDS,
-  LastOwnerError,
-  SESSION_COOKIE,
-  SESSION_MAX_AGE_SECONDS,
-  SessionExpiredError,
-  deriveUiCapabilities,
-  setSessionCookie,
-  signAudienceToken,
-  signSessionToken,
-  verifyAudienceToken,
-  verifySessionToken
-} from "./chunk-EM5DFHDZ.js";
+  getCollabProvider,
+  setCollabProvider
+} from "./chunk-2G2S36SY.js";
 import {
   BAKED_MEDIA_KEYS,
   EXT_TO_MIME,
@@ -37,6 +30,20 @@ import {
   sanitizeMediaName,
   setMediaProvider
 } from "./chunk-SOILPZ7U.js";
+import {
+  AUDIENCE_COOKIE,
+  AUDIENCE_MAX_AGE_SECONDS,
+  LastOwnerError,
+  SESSION_COOKIE,
+  SESSION_MAX_AGE_SECONDS,
+  SessionExpiredError,
+  deriveUiCapabilities,
+  setSessionCookie,
+  signAudienceToken,
+  signSessionToken,
+  verifyAudienceToken,
+  verifySessionToken
+} from "./chunk-EM5DFHDZ.js";
 import {
   CollabPeerSchema,
   HEARTBEAT_INTERVAL_MS,
@@ -46,10 +53,6 @@ import {
   SectionUpdateMessageSchema,
   TakeoverMessageSchema
 } from "./chunk-REM2NH7K.js";
-import {
-  getCollabProvider,
-  setCollabProvider
-} from "./chunk-2G2S36SY.js";
 import {
   AudienceColorSchema,
   AudienceNameSchema,
@@ -88,7 +91,7 @@ import {
   safeRedirect,
   suggestAccessibleOn,
   wcagLevel
-} from "./chunk-ABV7OZB3.js";
+} from "./chunk-CS2ECR3U.js";
 import {
   curatedIcons,
   getIcon
@@ -108,19 +111,30 @@ import {
 import {
   cn
 } from "./chunk-7EOSDFS3.js";
+import {
+  audiencePasses
+} from "./chunk-YBVK254P.js";
 import {
   isSameOriginRequest,
   requireSessionSecret,
   safeNextPath
 } from "./chunk-S2L3BPLS.js";
-import {
-  audiencePasses
-} from "./chunk-YBVK254P.js";
 import "./chunk-5BM2Y3NJ.js";
 import {
   getSectionContentSchema,
   getSectionSchema
 } from "./chunk-TZQPOR5A.js";
+import {
+  clearRegistry,
+  createRegistry,
+  defineSection,
+  getAllSchemas,
+  getAllSections,
+  getSchema,
+  getSection,
+  registerSchema,
+  registerSection
+} from "./chunk-VKAGMEKE.js";
 import {
   ChatbotConfigSchema,
   ChatbotTaskSchema,
@@ -143,17 +157,6 @@ import {
   VariantSchema,
   normalizeSiteIndex
 } from "./chunk-RHWWQV3J.js";
-import {
-  clearRegistry,
-  createRegistry,
-  defineSection,
-  getAllSchemas,
-  getAllSections,
-  getSchema,
-  getSection,
-  registerSchema,
-  registerSection
-} from "./chunk-VKAGMEKE.js";
 import "./chunk-FM4M4Q2W.js";
 import "./chunk-NSCT3AMV.js";
 import {
@@ -177,6 +180,8 @@ export {
   FontNameSchema,
   HEARTBEAT_INTERVAL_MS,
   HexColorSchema,
+  IDEMPOTENCY_KEY_RE,
+  IDEMPOTENCY_TRAILER,
   ImageManifestSchema,
   IndexSchema,
   IndexUpdateMessageSchema,
@@ -280,5 +285,6 @@ export {
   toSectionId,
   verifyAudienceToken,
   verifySessionToken,
-  wcagLevel
+  wcagLevel,
+  withIdempotencyTrailer
 };

package/dist/lib/index-ops.d.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import { type SiteIndex } from "../schemas/site-config";
+export declare const IndexOpSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    op: z.ZodLiteral<"insertAfter">;
+    pageId: z.ZodString;
+    afterId: z.ZodNullable<z.ZodString>;
+    sections: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodOptional<z.ZodEnum<{
+            draft: "draft";
+            live: "live";
+            archived: "archived";
+        }>>;
+        access: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"insertAt">;
+    pageId: z.ZodString;
+    position: z.ZodNumber;
+    sections: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodOptional<z.ZodEnum<{
+            draft: "draft";
+            live: "live";
+            archived: "archived";
+        }>>;
+        access: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"move">;
+    pageId: z.ZodString;
+    id: z.ZodString;
+    afterId: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"remove">;
+    ids: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"setMeta">;
+    id: z.ZodString;
+    status: z.ZodOptional<z.ZodEnum<{
+        draft: "draft";
+        live: "live";
+        archived: "archived";
+    }>>;
+    access: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"setPageMeta">;
+    pageId: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    slug: z.ZodOptional<z.ZodString>;
+    showInNav: z.ZodOptional<z.ZodBoolean>;
+    access: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>], "op">;
+export type IndexOp = z.infer<typeof IndexOpSchema>;
+export type ApplyIndexOpsResult = {
+    ok: true;
+    index: SiteIndex;
+    removedIds: string[];
+    warnings: string[];
+} | {
+    ok: false;
+    error: string;
+};
+/** Section-body types keyed by id, for the ids an insert op creates. */
+export declare function collectPostedTypes(sections: {
+    id: string;
+    content: unknown;
+}[] | undefined): Record<string, string>;
+/**
+ * Every section id the ops name, derivable from the ops ALONE (no index read).
+ * Callers need this before applying anything: the collab broadcast has to tell
+ * browser editors which rows moved, and the audit trail has to record that an
+ * ops-only save touched anything at all. `setPageMeta` names no section.
+ */
+export declare function opTouchedSectionIds(ops: IndexOp[]): string[];
+export declare function applyIndexOps(rawIndex: unknown, ops: IndexOp[], newSectionTypes: Record<string, string>): ApplyIndexOpsResult;
+//# sourceMappingURL=index-ops.d.ts.map

package/dist/lib/index-ops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-ops.d.ts","sourceRoot":"","sources":["../../src/lib/index-ops.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAA+B,KAAK,SAAS,EAAoB,MAAM,wBAAwB,CAAC;AAgCvG,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;yBAqCxB,CAAC;AAEH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAEpD,MAAM,MAAM,mBAAmB,GAC3B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,GACxE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjC,wEAAwE;AACxE,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,EAAE,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOnH;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,MAAM,EAAE,CAQ5D;AAID,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,OAAO,EACjB,GAAG,EAAE,OAAO,EAAE,EACd,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACtC,mBAAmB,CAsMrB"}

package/dist/lib/index-ops.js

@@ -0,0 +1,223 @@
+import {
+  IndexSchema,
+  RESERVED_SLUGS
+} from "../chunk-RHWWQV3J.js";
+import "../chunk-FM4M4Q2W.js";
+import "../chunk-JSBRDJBE.js";
+
+// src/lib/index-ops.ts
+import { z } from "zod";
+var OpStatusSchema = z.enum(["draft", "live", "archived"]);
+var SAFE_SECTION_ID = /^[a-zA-Z0-9_-]{1,64}$/;
+var SectionInsertSchema = z.object({
+  id: z.string().regex(SAFE_SECTION_ID, "Section ids may only contain letters, numbers, dashes and underscores (max 64 chars) \u2014 they become filenames.").describe("The new section's id: letters, numbers, dashes, underscores; max 64 chars. Must not already exist in the index."),
+  status: OpStatusSchema.optional().describe('Defaults to "draft" \u2014 invisible to viewers until promoted to "live".'),
+  access: z.array(z.string()).optional().describe("Audience slugs from list_audiences. Defaults to [] (everyone).")
+});
+var IndexOpSchema = z.discriminatedUnion("op", [
+  z.object({
+    op: z.literal("insertAfter"),
+    pageId: z.string().describe("The page whose order receives the sections."),
+    afterId: z.string().nullable().describe("Insert directly after this section id, or null for the start of the page."),
+    sections: z.array(SectionInsertSchema).min(1).describe("Sections to create, in the order they should appear. Each needs its body in this call's `sections`.")
+  }),
+  z.object({
+    op: z.literal("insertAt"),
+    pageId: z.string().describe("The page whose order receives the sections."),
+    position: z.number().int().min(0).describe("0-based index in the page's order; equal to the order's length appends."),
+    sections: z.array(SectionInsertSchema).min(1).describe("Sections to create, in the order they should appear. Each needs its body in this call's `sections`.")
+  }),
+  z.object({
+    op: z.literal("move"),
+    pageId: z.string().describe("Destination page id (may be the section's current page)."),
+    id: z.string().describe("The existing section to move."),
+    afterId: z.string().nullable().describe("Place it directly after this section id in the destination page, or null for the start.")
+  }),
+  z.object({
+    op: z.literal("remove"),
+    ids: z.array(z.string()).min(1).describe("Sections to delete: removed from the page order AND from sections{}, and their content files are deleted.")
+  }),
+  z.object({
+    op: z.literal("setMeta"),
+    id: z.string().describe("An existing section id."),
+    status: OpStatusSchema.optional().describe('New status. "live" is what makes a section visible to viewers.'),
+    access: z.array(z.string()).optional().describe("New audience slugs from list_audiences; [] means everyone.")
+  }),
+  z.object({
+    op: z.literal("setPageMeta"),
+    pageId: z.string().describe("An existing page id."),
+    title: z.string().optional().describe("New page title."),
+    slug: z.string().optional().describe("New URL slug (lowercase words joined by dashes). Not settable on the home page, whose slug is always empty."),
+    showInNav: z.boolean().optional().describe("Whether the page appears in site navigation."),
+    access: z.array(z.string()).optional().describe("New audience slugs from list_audiences; [] means everyone.")
+  })
+]);
+function collectPostedTypes(sections) {
+  const types = {};
+  for (const s of sections ?? []) {
+    const type = s.content?.type;
+    if (typeof type === "string") types[s.id] = type;
+  }
+  return types;
+}
+function opTouchedSectionIds(ops) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const op of ops) {
+    if (op.op === "insertAfter" || op.op === "insertAt") for (const s of op.sections) ids.add(s.id);
+    else if (op.op === "move" || op.op === "setMeta") ids.add(op.id);
+    else if (op.op === "remove") for (const id of op.ids) ids.add(id);
+  }
+  return [...ids];
+}
+var fmt = (ids) => ids.map((id) => `"${id}"`).join(", ");
+function applyIndexOps(rawIndex, ops, newSectionTypes) {
+  const base = IndexSchema.safeParse(rawIndex);
+  if (!base.success) {
+    return {
+      ok: false,
+      error: "the site's current index could not be parsed, so indexOps cannot be applied \u2014 read it with get_site_index and post a repaired full `index` instead. " + base.error.issues.map((i) => i.message).join("; ")
+    };
+  }
+  const index = {
+    ...base.data,
+    pages: base.data.pages.map((p) => ({ ...p, order: [...p.order] })),
+    sections: Object.fromEntries(Object.entries(base.data.sections).map(([k, v]) => [k, { ...v }]))
+  };
+  const removed = /* @__PURE__ */ new Set();
+  const warnings = [];
+  const fail = (error) => ({ ok: false, error });
+  for (const [i, op] of ops.entries()) {
+    const at = `indexOps[${i}] ${op.op}`;
+    if (op.op === "insertAfter" || op.op === "insertAt") {
+      const page2 = index.pages.find((p) => p.id === op.pageId);
+      if (!page2) return fail(`${at}: no page with id "${op.pageId}" \u2014 page ids come from get_site_index.`);
+      let position;
+      if (op.op === "insertAfter") {
+        if (op.afterId === null) position = 0;
+        else {
+          const idx = page2.order.indexOf(op.afterId);
+          if (idx === -1) return fail(`${at}: afterId "${op.afterId}" is not in page "${op.pageId}"'s order.`);
+          position = idx + 1;
+        }
+      } else {
+        if (op.position > page2.order.length) {
+          return fail(`${at}: position ${op.position} is out of range for page "${op.pageId}" (valid: 0..${page2.order.length}).`);
+        }
+        position = op.position;
+      }
+      const metas = [];
+      const seen = /* @__PURE__ */ new Set();
+      for (const s of op.sections) {
+        if (seen.has(s.id)) return fail(`${at}: section "${s.id}" is listed twice in this op's \`sections\`.`);
+        seen.add(s.id);
+        if (index.sections[s.id]) {
+          return fail(`${at}: section "${s.id}" already exists in the index \u2014 use move to relocate it, or setMeta to change its status/access.`);
+        }
+        if (!SAFE_SECTION_ID.test(s.id)) {
+          return fail(`${at}: section id "${s.id}" is not usable \u2014 ids become filenames, so they may only contain letters, numbers, dashes and underscores (max 64 chars).`);
+        }
+        const type = newSectionTypes[s.id];
+        if (!type) {
+          return fail(`${at}: section "${s.id}" has no usable body in this call \u2014 post its full body ({ "type": "...", "content": {...} }) in \`sections\` in the same save; an inserted section's type comes from the body.`);
+        }
+        const meta = { type, status: s.status ?? "draft", access: s.access ?? [] };
+        const stranded = page2.access.length > 0 ? meta.access.filter((a) => !page2.access.includes(a)) : [];
+        if (stranded.length > 0) {
+          warnings.push(
+            `${at}: section "${s.id}" carries audience(s) ${fmt(stranded)} that page "${op.pageId}" does not allow, so no audienced viewer will see it \u2014 clear it with setMeta, or widen the page's access.`
+          );
+        }
+        metas.push([s.id, meta]);
+      }
+      page2.order.splice(position, 0, ...metas.map(([id]) => id));
+      for (const [id, meta] of metas) index.sections[id] = meta;
+      continue;
+    }
+    if (op.op === "move") {
+      const meta = index.sections[op.id];
+      if (!meta) return fail(`${at}: section "${op.id}" is not in the index.`);
+      const dest = index.pages.find((p) => p.id === op.pageId);
+      if (!dest) return fail(`${at}: no page with id "${op.pageId}" \u2014 page ids come from get_site_index.`);
+      if (op.afterId === op.id) return fail(`${at}: cannot move section "${op.id}" after itself.`);
+      for (const p of index.pages) {
+        const idx = p.order.indexOf(op.id);
+        if (idx !== -1) p.order.splice(idx, 1);
+      }
+      let position;
+      if (op.afterId === null) position = 0;
+      else {
+        const idx = dest.order.indexOf(op.afterId);
+        if (idx === -1) return fail(`${at}: afterId "${op.afterId}" is not in destination page "${op.pageId}"'s order.`);
+        position = idx + 1;
+      }
+      dest.order.splice(position, 0, op.id);
+      const stranded = dest.access.length > 0 ? meta.access.filter((a) => !dest.access.includes(a)) : [];
+      if (stranded.length > 0) {
+        warnings.push(
+          `${at}: section "${op.id}" carries audience(s) ${fmt(stranded)} that page "${op.pageId}" does not allow, so no audienced viewer will see it \u2014 clear it with setMeta, or widen the page's access.`
+        );
+      }
+      continue;
+    }
+    if (op.op === "remove") {
+      for (const id of op.ids) {
+        if (!index.sections[id]) return fail(`${at}: section "${id}" is not in the index.`);
+        delete index.sections[id];
+        for (const p of index.pages) {
+          const idx = p.order.indexOf(id);
+          if (idx !== -1) p.order.splice(idx, 1);
+        }
+        removed.add(id);
+      }
+      continue;
+    }
+    if (op.op === "setMeta") {
+      if (op.status === void 0 && op.access === void 0) {
+        return fail(`${at}: nothing to set \u2014 provide status and/or access.`);
+      }
+      const meta = index.sections[op.id];
+      if (!meta) return fail(`${at}: section "${op.id}" is not in the index.`);
+      if (op.status !== void 0) meta.status = op.status;
+      if (op.access !== void 0) meta.access = op.access;
+      continue;
+    }
+    if (op.title === void 0 && op.slug === void 0 && op.showInNav === void 0 && op.access === void 0) {
+      return fail(`${at}: nothing to set \u2014 provide title, slug, showInNav and/or access.`);
+    }
+    const page = index.pages.find((p) => p.id === op.pageId);
+    if (!page) return fail(`${at}: no page with id "${op.pageId}" \u2014 page ids come from get_site_index.`);
+    if (op.slug !== void 0 && page.isHome) {
+      return fail(`${at}: the home page's slug is always empty and cannot be set. Promote a different page to home in the editor if you need to change which page is the root.`);
+    }
+    if (op.slug !== void 0 && RESERVED_SLUGS.includes(op.slug)) {
+      return fail(`${at}: slug "${op.slug}" is reserved by a platform route and would shadow this page. Pick another slug.`);
+    }
+    if (op.title !== void 0) page.title = op.title;
+    if (op.slug !== void 0) page.slug = op.slug;
+    if (op.showInNav !== void 0) page.showInNav = op.showInNav;
+    if (op.access !== void 0) {
+      const dropped = page.access.filter((a) => !op.access.includes(a));
+      page.access = op.access;
+      if (dropped.length > 0 && op.access.length > 0) {
+        const stranded = page.order.filter((id) => index.sections[id]?.access.some((a) => dropped.includes(a)));
+        if (stranded.length > 0) {
+          warnings.push(
+            `${at}: section(s) ${fmt(stranded)} still carry audience(s) ${fmt(dropped)} that page "${op.pageId}" no longer allows, so no audienced viewer will see them \u2014 clear them with setMeta.`
+          );
+        }
+      }
+    }
+  }
+  const removedIds = [...removed].filter((id) => !index.sections[id]);
+  const validated = IndexSchema.safeParse(index);
+  if (!validated.success) {
+    return fail(`applying indexOps produced an invalid index: ${validated.error.issues.map((issue) => issue.message).join("; ")}`);
+  }
+  return { ok: true, index: validated.data, removedIds, warnings };
+}
+export {
+  IndexOpSchema,
+  applyIndexOps,
+  collectPostedTypes,
+  opTouchedSectionIds
+};

package/dist/lib/index.js

@@ -18,7 +18,7 @@ import {
   safeRedirect,
   suggestAccessibleOn,
   wcagLevel
-} from "../chunk-ABV7OZB3.js";
+} from "../chunk-CS2ECR3U.js";
 import {
   curatedIcons,
   getIcon
@@ -38,13 +38,12 @@ import {
 import {
   cn
 } from "../chunk-7EOSDFS3.js";
-import "../chunk-S2L3BPLS.js";
 import {
   audiencePasses
 } from "../chunk-YBVK254P.js";
+import "../chunk-S2L3BPLS.js";
 import "../chunk-5BM2Y3NJ.js";
 import "../chunk-TZQPOR5A.js";
-import "../chunk-RHWWQV3J.js";
 import {
   clearRegistry,
   createRegistry,
@@ -56,6 +55,7 @@ import {
   registerSchema,
   registerSection
 } from "../chunk-VKAGMEKE.js";
+import "../chunk-RHWWQV3J.js";
 import "../chunk-FM4M4Q2W.js";
 import "../chunk-NSCT3AMV.js";
 import {

package/dist/schemas/index.js

@@ -20,6 +20,7 @@ import {
   getSectionContentSchema,
   getSectionSchema
 } from "../chunk-TZQPOR5A.js";
+import "../chunk-VKAGMEKE.js";
 import {
   ChatbotConfigSchema,
   ChatbotTaskSchema,
@@ -42,7 +43,6 @@ import {
   VariantSchema,
   normalizeSiteIndex
 } from "../chunk-RHWWQV3J.js";
-import "../chunk-VKAGMEKE.js";
 import "../chunk-FM4M4Q2W.js";
 import "../chunk-NSCT3AMV.js";
 import "../chunk-JSBRDJBE.js";

package/dist/storage/index.d.ts

@@ -1,3 +1,3 @@
 export type { StorageProvider, FileWrite, AssetStore } from "./types";
-export { StorageConflictError, ASSET_CACHE_CONTROL } from "./types";
+export { StorageConflictError, ASSET_CACHE_CONTROL, IDEMPOTENCY_TRAILER, IDEMPOTENCY_KEY_RE, withIdempotencyTrailer } from "./types";
 //# sourceMappingURL=index.d.ts.map

package/dist/storage/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACtE,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACtE,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC"}

package/dist/storage/index.js

@@ -1,9 +1,15 @@
 import {
   ASSET_CACHE_CONTROL,
-  StorageConflictError
-} from "../chunk-VAOW4WXQ.js";
+  IDEMPOTENCY_KEY_RE,
+  IDEMPOTENCY_TRAILER,
+  StorageConflictError,
+  withIdempotencyTrailer
+} from "../chunk-EUSWEVOA.js";
 import "../chunk-JSBRDJBE.js";
 export {
   ASSET_CACHE_CONTROL,
-  StorageConflictError
+  IDEMPOTENCY_KEY_RE,
+  IDEMPOTENCY_TRAILER,
+  StorageConflictError,
+  withIdempotencyTrailer
 };

package/dist/storage/types.d.ts

@@ -24,7 +24,51 @@ export interface StorageProvider {
     listDirectory(path: string, options?: {
         draft?: boolean;
     }): Promise<string[]>;
+    /**
+     * Find a recent commit on the draft branch whose message carries the given
+     * `Idempotency-Key:` trailer, returning its sha (null if not found).
+     *
+     * This exists to make a retried write LEGIBLE, not to make it safe — safety is
+     * already `writeFiles`' baseVersion check, which a retry cannot get past once
+     * the original landed (the head moved, so the retry's baseVersion is stale).
+     * What the check cannot do is tell "your write failed" from "your write
+     * succeeded and you didn't hear back", and it reports both as a conflict. A
+     * caller that tagged its write can ask that question here.
+     *
+     * OPTIONAL: providers that cannot search history omit it, and callers fall
+     * back to surfacing the plain conflict.
+     *
+     * Best-effort by contract. It searches a BOUNDED window, so an old key reads
+     * as absent, and an implementation may answer "not found" when the history
+     * read itself fails — failing closed keeps the conflict rather than inventing
+     * a replay. So `null` means "could not confirm", NOT "your write did not
+     * land": a caller must not tell the user the earlier attempt failed.
+     */
+    findCommitByIdempotencyKey?(key: string, options?: {
+        limit?: number;
+    }): Promise<string | null>;
 }
+/**
+ * Commit-message trailer carrying a write's idempotency key. The commit itself is
+ * the store — no table, and no TTL to tune: keys live exactly as long as the
+ * draft branch, and `promoteDraft` deletes it, which is the correct lifetime
+ * (after a publish there is no draft, so an old write must not replay).
+ */
+export declare const IDEMPOTENCY_TRAILER = "Idempotency-Key";
+/**
+ * Keys are interpolated into a commit message, so the charset is enforced HERE,
+ * at the interpolation point, and not only by the caller that happens to have a
+ * schema. A key containing a newline would let a caller append arbitrary further
+ * trailer lines to the commit.
+ */
+export declare const IDEMPOTENCY_KEY_RE: RegExp;
+/**
+ * Build a commit message carrying `key` as a trailer, or return `subject`
+ * unchanged when no key is given. Throws on a malformed key: every caller
+ * reaches this through a write path that should have validated first, so an
+ * invalid key here is a bug, not user input to be tolerated.
+ */
+export declare function withIdempotencyTrailer(subject: string, key?: string): string;
 export type FileWrite = {
     path: string;
     content: string | Uint8Array | null;

package/dist/storage/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/storage/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;aACjB,cAAc,EAAE,MAAM,GAAG,IAAI;gBAA7B,cAAc,EAAE,MAAM,GAAG,IAAI;CAI1D;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,CACR,KAAK,EAAE,SAAS,EAAE,EAClB,OAAO,EAAE,MAAM,EAIf,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GACxC,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEhC,QAAQ,CACN,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAC5B,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAE9B,YAAY,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAE7C,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAE9B,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAC/E;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;CAC/B,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,gCAAgC,CAAC;AAEjE;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,6DAA6D;IAC7D,eAAe,CACb,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,GAC5B,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEnE,oEAAoE;IACpE,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAEnC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvC,sDAAsD;IACtD,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC,CAAC;CACpF"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/storage/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;aACjB,cAAc,EAAE,MAAM,GAAG,IAAI;gBAA7B,cAAc,EAAE,MAAM,GAAG,IAAI;CAI1D;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,CACR,KAAK,EAAE,SAAS,EAAE,EAClB,OAAO,EAAE,MAAM,EAIf,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GACxC,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEhC,QAAQ,CACN,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAC5B,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAE9B,YAAY,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAE7C,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAE9B,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAE9E;;;;;;;;;;;;;;;;;;;OAmBG;IACH,0BAA0B,CAAC,CACzB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAC3B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC3B;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AAErD;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,QAA6B,CAAC;AAE7D;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAM5E;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;CAC/B,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,gCAAgC,CAAC;AAEjE;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,6DAA6D;IAC7D,eAAe,CACb,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,GAC5B,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEnE,oEAAoE;IACpE,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAEnC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvC,sDAAsD;IACtD,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC,CAAC;CACpF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drawnagency/primitives",
-  "version": "0.1.95",
+  "version": "0.1.96",
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
@@ -60,6 +60,10 @@
       "types": "./dist/lib/registry.d.ts",
       "default": "./dist/lib/registry.js"
     },
+    "./lib/index-ops": {
+      "types": "./dist/lib/index-ops.d.ts",
+      "default": "./dist/lib/index-ops.js"
+    },
     "./lib/media-folders": {
       "types": "./dist/lib/media-folders.d.ts",
       "default": "./dist/lib/media-folders.js"

package/src/lib/index-ops.ts

@@ -0,0 +1,309 @@
+import { z } from "zod";
+import { IndexSchema, RESERVED_SLUGS, type SiteIndex, type SectionMeta } from "../schemas/site-config";
+
+/**
+ * Server-applied index deltas for the MCP connector's save path. An agent
+ * cannot reliably hand-transcribe a real site's 40–51 KB index into a tool
+ * parameter (two consecutive attempts each introduced an id-level slip), so
+ * structural edits are expressed as ops and applied here against the index the
+ * write is concurrency-checked against.
+ *
+ * Pure by contract: no I/O, no storage, no octokit. The caller owns reading the
+ * base index at the right commit and committing the result.
+ */
+
+// The three canonical statuses. Deliberately a plain enum rather than the
+// schemas' StatusSchema (a ZodPipe with a "published" -> "live" transform):
+// this shape is converted to JSON Schema for MCP clients, so it stays a flat
+// enum, and reads never surface "published" anyway (they return normalized
+// values).
+const OpStatusSchema = z.enum(["draft", "live", "archived"]);
+
+// Must match content-ops' SAFE_SECTION_ID: the id becomes a FILENAME
+// (src/content/sections/<id>.json). Enforced here so a bad id is a named op
+// error rather than a bare "[input] Invalid section ID" from deep in the write
+// path, which names neither the op nor the id.
+const SAFE_SECTION_ID = /^[a-zA-Z0-9_-]{1,64}$/;
+
+const SectionInsertSchema = z.object({
+  id: z.string().regex(SAFE_SECTION_ID, "Section ids may only contain letters, numbers, dashes and underscores (max 64 chars) — they become filenames.").describe("The new section's id: letters, numbers, dashes, underscores; max 64 chars. Must not already exist in the index."),
+  status: OpStatusSchema.optional().describe('Defaults to "draft" — invisible to viewers until promoted to "live".'),
+  access: z.array(z.string()).optional().describe("Audience slugs from list_audiences. Defaults to [] (everyone)."),
+});
+
+export const IndexOpSchema = z.discriminatedUnion("op", [
+  z.object({
+    op: z.literal("insertAfter"),
+    pageId: z.string().describe("The page whose order receives the sections."),
+    afterId: z.string().nullable().describe("Insert directly after this section id, or null for the start of the page."),
+    sections: z.array(SectionInsertSchema).min(1).describe("Sections to create, in the order they should appear. Each needs its body in this call's `sections`."),
+  }),
+  z.object({
+    op: z.literal("insertAt"),
+    pageId: z.string().describe("The page whose order receives the sections."),
+    position: z.number().int().min(0).describe("0-based index in the page's order; equal to the order's length appends."),
+    sections: z.array(SectionInsertSchema).min(1).describe("Sections to create, in the order they should appear. Each needs its body in this call's `sections`."),
+  }),
+  z.object({
+    op: z.literal("move"),
+    pageId: z.string().describe("Destination page id (may be the section's current page)."),
+    id: z.string().describe("The existing section to move."),
+    afterId: z.string().nullable().describe("Place it directly after this section id in the destination page, or null for the start."),
+  }),
+  z.object({
+    op: z.literal("remove"),
+    ids: z.array(z.string()).min(1).describe("Sections to delete: removed from the page order AND from sections{}, and their content files are deleted."),
+  }),
+  z.object({
+    op: z.literal("setMeta"),
+    id: z.string().describe("An existing section id."),
+    status: OpStatusSchema.optional().describe('New status. "live" is what makes a section visible to viewers.'),
+    access: z.array(z.string()).optional().describe("New audience slugs from list_audiences; [] means everyone."),
+  }),
+  z.object({
+    op: z.literal("setPageMeta"),
+    pageId: z.string().describe("An existing page id."),
+    title: z.string().optional().describe("New page title."),
+    slug: z.string().optional().describe("New URL slug (lowercase words joined by dashes). Not settable on the home page, whose slug is always empty."),
+    showInNav: z.boolean().optional().describe("Whether the page appears in site navigation."),
+    access: z.array(z.string()).optional().describe("New audience slugs from list_audiences; [] means everyone."),
+  }),
+]);
+
+export type IndexOp = z.infer<typeof IndexOpSchema>;
+
+export type ApplyIndexOpsResult =
+  | { ok: true; index: SiteIndex; removedIds: string[]; warnings: string[] }
+  | { ok: false; error: string };
+
+/** Section-body types keyed by id, for the ids an insert op creates. */
+export function collectPostedTypes(sections: { id: string; content: unknown }[] | undefined): Record<string, string> {
+  const types: Record<string, string> = {};
+  for (const s of sections ?? []) {
+    const type = (s.content as { type?: unknown } | null | undefined)?.type;
+    if (typeof type === "string") types[s.id] = type;
+  }
+  return types;
+}
+
+/**
+ * Every section id the ops name, derivable from the ops ALONE (no index read).
+ * Callers need this before applying anything: the collab broadcast has to tell
+ * browser editors which rows moved, and the audit trail has to record that an
+ * ops-only save touched anything at all. `setPageMeta` names no section.
+ */
+export function opTouchedSectionIds(ops: IndexOp[]): string[] {
+  const ids = new Set<string>();
+  for (const op of ops) {
+    if (op.op === "insertAfter" || op.op === "insertAt") for (const s of op.sections) ids.add(s.id);
+    else if (op.op === "move" || op.op === "setMeta") ids.add(op.id);
+    else if (op.op === "remove") for (const id of op.ids) ids.add(id);
+  }
+  return [...ids];
+}
+
+const fmt = (ids: string[]) => ids.map((id) => `"${id}"`).join(", ");
+
+export function applyIndexOps(
+  rawIndex: unknown,
+  ops: IndexOp[],
+  newSectionTypes: Record<string, string>,
+): ApplyIndexOpsResult {
+  // Apply to the CANONICAL shape, not the raw one: a legacy index
+  // (`order`/`sections` with no `pages`) normalizes into a synthetic home page
+  // carrying those ids, and ops against the raw shape would find no pages at
+  // all and silently miss every id.
+  const base = IndexSchema.safeParse(rawIndex);
+  if (!base.success) {
+    return {
+      ok: false,
+      error:
+        "the site's current index could not be parsed, so indexOps cannot be applied — read it with get_site_index and post a repaired full `index` instead. " +
+        base.error.issues.map((i) => i.message).join("; "),
+    };
+  }
+
+  // Own copy: the caller's index is also its knownSiteTypes source and may be
+  // logged, so nothing here mutates it.
+  const index: SiteIndex = {
+    ...base.data,
+    pages: base.data.pages.map((p) => ({ ...p, order: [...p.order] })),
+    sections: Object.fromEntries(Object.entries(base.data.sections).map(([k, v]) => [k, { ...v }])),
+  };
+
+  const removed = new Set<string>();
+  const warnings: string[] = [];
+  const fail = (error: string): ApplyIndexOpsResult => ({ ok: false, error });
+
+  for (const [i, op] of ops.entries()) {
+    const at = `indexOps[${i}] ${op.op}`;
+
+    if (op.op === "insertAfter" || op.op === "insertAt") {
+      const page = index.pages.find((p) => p.id === op.pageId);
+      if (!page) return fail(`${at}: no page with id "${op.pageId}" — page ids come from get_site_index.`);
+
+      let position: number;
+      if (op.op === "insertAfter") {
+        if (op.afterId === null) position = 0;
+        else {
+          const idx = page.order.indexOf(op.afterId);
+          if (idx === -1) return fail(`${at}: afterId "${op.afterId}" is not in page "${op.pageId}"'s order.`);
+          position = idx + 1;
+        }
+      } else {
+        if (op.position > page.order.length) {
+          return fail(`${at}: position ${op.position} is out of range for page "${op.pageId}" (valid: 0..${page.order.length}).`);
+        }
+        position = op.position;
+      }
+
+      const metas: [string, SectionMeta][] = [];
+      // Ids in THIS op are not in `index.sections` yet, so the existence check
+      // below cannot see them — without a local seen-set a repeated id splices
+      // twice and only fails at the final re-validation, as "appears in more
+      // than one page order" with no op index and a misleading description.
+      const seen = new Set<string>();
+      for (const s of op.sections) {
+        if (seen.has(s.id)) return fail(`${at}: section "${s.id}" is listed twice in this op's \`sections\`.`);
+        seen.add(s.id);
+        if (index.sections[s.id]) {
+          return fail(`${at}: section "${s.id}" already exists in the index — use move to relocate it, or setMeta to change its status/access.`);
+        }
+        if (!SAFE_SECTION_ID.test(s.id)) {
+          return fail(`${at}: section id "${s.id}" is not usable — ids become filenames, so they may only contain letters, numbers, dashes and underscores (max 64 chars).`);
+        }
+        const type = newSectionTypes[s.id];
+        if (!type) {
+          // Covers both "no body posted" and "body posted but its `type` is
+          // missing or not a string" — collectPostedTypes only records usable
+          // string types, so this cannot tell them apart, and the old wording
+          // ("has no body") sent an agent hunting for a body that was right there.
+          return fail(`${at}: section "${s.id}" has no usable body in this call — post its full body ({ "type": "...", "content": {...} }) in \`sections\` in the same save; an inserted section's type comes from the body.`);
+        }
+        const meta: SectionMeta = { type, status: s.status ?? "draft", access: s.access ?? [] };
+        // Same advisory as `move`: an inserted section whose audiences the
+        // destination page does not allow is invisible to every audienced
+        // viewer, and saying nothing would make that look like a successful save.
+        const stranded = page.access.length > 0 ? meta.access.filter((a) => !page.access.includes(a)) : [];
+        if (stranded.length > 0) {
+          warnings.push(
+            `${at}: section "${s.id}" carries audience(s) ${fmt(stranded)} that page "${op.pageId}" does not allow, so no audienced viewer will see it — clear it with setMeta, or widen the page's access.`,
+          );
+        }
+        metas.push([s.id, meta]);
+      }
+      page.order.splice(position, 0, ...metas.map(([id]) => id));
+      for (const [id, meta] of metas) index.sections[id] = meta;
+      continue;
+    }
+
+    if (op.op === "move") {
+      const meta = index.sections[op.id];
+      if (!meta) return fail(`${at}: section "${op.id}" is not in the index.`);
+      const dest = index.pages.find((p) => p.id === op.pageId);
+      if (!dest) return fail(`${at}: no page with id "${op.pageId}" — page ids come from get_site_index.`);
+      if (op.afterId === op.id) return fail(`${at}: cannot move section "${op.id}" after itself.`);
+
+      for (const p of index.pages) {
+        const idx = p.order.indexOf(op.id);
+        if (idx !== -1) p.order.splice(idx, 1);
+      }
+      let position: number;
+      if (op.afterId === null) position = 0;
+      else {
+        const idx = dest.order.indexOf(op.afterId);
+        if (idx === -1) return fail(`${at}: afterId "${op.afterId}" is not in destination page "${op.pageId}"'s order.`);
+        position = idx + 1;
+      }
+      dest.order.splice(position, 0, op.id);
+
+      // Advisory, never a silent rewrite: the editor's moveSection resets an
+      // incompatible section access, but an API doing that invisibly would
+      // change who can see content without saying so. "no audienced viewer",
+      // not "everyone" — audiencePasses returns true for a viewer with no
+      // audience at all (lib/pages.ts).
+      const stranded = dest.access.length > 0 ? meta.access.filter((a) => !dest.access.includes(a)) : [];
+      if (stranded.length > 0) {
+        warnings.push(
+          `${at}: section "${op.id}" carries audience(s) ${fmt(stranded)} that page "${op.pageId}" does not allow, so no audienced viewer will see it — clear it with setMeta, or widen the page's access.`,
+        );
+      }
+      continue;
+    }
+
+    if (op.op === "remove") {
+      for (const id of op.ids) {
+        if (!index.sections[id]) return fail(`${at}: section "${id}" is not in the index.`);
+        delete index.sections[id];
+        for (const p of index.pages) {
+          const idx = p.order.indexOf(id);
+          if (idx !== -1) p.order.splice(idx, 1);
+        }
+        removed.add(id);
+      }
+      continue;
+    }
+
+    if (op.op === "setMeta") {
+      if (op.status === undefined && op.access === undefined) {
+        return fail(`${at}: nothing to set — provide status and/or access.`);
+      }
+      const meta = index.sections[op.id];
+      if (!meta) return fail(`${at}: section "${op.id}" is not in the index.`);
+      if (op.status !== undefined) meta.status = op.status;
+      if (op.access !== undefined) meta.access = op.access;
+      continue;
+    }
+
+    // setPageMeta
+    if (op.title === undefined && op.slug === undefined && op.showInNav === undefined && op.access === undefined) {
+      return fail(`${at}: nothing to set — provide title, slug, showInNav and/or access.`);
+    }
+    const page = index.pages.find((p) => p.id === op.pageId);
+    if (!page) return fail(`${at}: no page with id "${op.pageId}" — page ids come from get_site_index.`);
+    if (op.slug !== undefined && page.isHome) {
+      return fail(`${at}: the home page's slug is always empty and cannot be set. Promote a different page to home in the editor if you need to change which page is the root.`);
+    }
+    // IndexSchema hard-rejects only the five slugs reserved before client sites
+    // existed (PARSE_REJECTED_SLUGS) — the newer ones ("present", "print") are
+    // enforced at AUTHORING time on purpose, so a grandfathered index still
+    // loads (see schemas/site-config.ts). This is an authoring surface, so it
+    // owns that enforcement; without it a page silently disappears behind an
+    // injected platform route with no error anywhere.
+    if (op.slug !== undefined && (RESERVED_SLUGS as readonly string[]).includes(op.slug)) {
+      return fail(`${at}: slug "${op.slug}" is reserved by a platform route and would shadow this page. Pick another slug.`);
+    }
+    if (op.title !== undefined) page.title = op.title;
+    if (op.slug !== undefined) page.slug = op.slug;
+    if (op.showInNav !== undefined) page.showInNav = op.showInNav;
+    if (op.access !== undefined) {
+      const dropped = page.access.filter((a) => !op.access!.includes(a));
+      page.access = op.access;
+      if (dropped.length > 0 && op.access.length > 0) {
+        const stranded = page.order.filter((id) => index.sections[id]?.access.some((a) => dropped.includes(a)));
+        if (stranded.length > 0) {
+          warnings.push(
+            `${at}: section(s) ${fmt(stranded)} still carry audience(s) ${fmt(dropped)} that page "${op.pageId}" no longer allows, so no audienced viewer will see them — clear them with setMeta.`,
+          );
+        }
+      }
+    }
+  }
+
+  // A remove followed by a re-insert of the same id is a net no-op for files:
+  // reporting it for deletion would delete the file the resulting index
+  // references, and content-ops' stillReferenced guard would reject the write.
+  const removedIds = [...removed].filter((id) => !index.sections[id]);
+
+  // Ops cannot break the order/sections partition by construction, but they can
+  // break page-level invariants the ops above do not check themselves: a
+  // duplicate slug, an invalid slug shape, one of the five parse-rejected legacy
+  // slugs. Re-run the canonical validation so the caller gets those named here
+  // rather than as an opaque ZodError from the write path. (The NEWER reserved
+  // slugs are not in that set — setPageMeta checks them itself, above.)
+  const validated = IndexSchema.safeParse(index);
+  if (!validated.success) {
+    return fail(`applying indexOps produced an invalid index: ${validated.error.issues.map((issue) => issue.message).join("; ")}`);
+  }
+  return { ok: true, index: validated.data, removedIds, warnings };
+}

package/src/storage/index.ts

@@ -1,2 +1,2 @@
 export type { StorageProvider, FileWrite, AssetStore } from "./types";
-export { StorageConflictError, ASSET_CACHE_CONTROL } from "./types";
+export { StorageConflictError, ASSET_CACHE_CONTROL, IDEMPOTENCY_TRAILER, IDEMPOTENCY_KEY_RE, withIdempotencyTrailer } from "./types";

package/src/storage/types.ts

@@ -31,6 +31,61 @@ export interface StorageProvider {
   getVersion(): Promise<string>;
 
   listDirectory(path: string, options?: { draft?: boolean }): Promise<string[]>;
+
+  /**
+   * Find a recent commit on the draft branch whose message carries the given
+   * `Idempotency-Key:` trailer, returning its sha (null if not found).
+   *
+   * This exists to make a retried write LEGIBLE, not to make it safe — safety is
+   * already `writeFiles`' baseVersion check, which a retry cannot get past once
+   * the original landed (the head moved, so the retry's baseVersion is stale).
+   * What the check cannot do is tell "your write failed" from "your write
+   * succeeded and you didn't hear back", and it reports both as a conflict. A
+   * caller that tagged its write can ask that question here.
+   *
+   * OPTIONAL: providers that cannot search history omit it, and callers fall
+   * back to surfacing the plain conflict.
+   *
+   * Best-effort by contract. It searches a BOUNDED window, so an old key reads
+   * as absent, and an implementation may answer "not found" when the history
+   * read itself fails — failing closed keeps the conflict rather than inventing
+   * a replay. So `null` means "could not confirm", NOT "your write did not
+   * land": a caller must not tell the user the earlier attempt failed.
+   */
+  findCommitByIdempotencyKey?(
+    key: string,
+    options?: { limit?: number },
+  ): Promise<string | null>;
+}
+
+/**
+ * Commit-message trailer carrying a write's idempotency key. The commit itself is
+ * the store — no table, and no TTL to tune: keys live exactly as long as the
+ * draft branch, and `promoteDraft` deletes it, which is the correct lifetime
+ * (after a publish there is no draft, so an old write must not replay).
+ */
+export const IDEMPOTENCY_TRAILER = "Idempotency-Key";
+
+/**
+ * Keys are interpolated into a commit message, so the charset is enforced HERE,
+ * at the interpolation point, and not only by the caller that happens to have a
+ * schema. A key containing a newline would let a caller append arbitrary further
+ * trailer lines to the commit.
+ */
+export const IDEMPOTENCY_KEY_RE = /^[A-Za-z0-9._:-]{8,200}$/;
+
+/**
+ * Build a commit message carrying `key` as a trailer, or return `subject`
+ * unchanged when no key is given. Throws on a malformed key: every caller
+ * reaches this through a write path that should have validated first, so an
+ * invalid key here is a bug, not user input to be tolerated.
+ */
+export function withIdempotencyTrailer(subject: string, key?: string): string {
+  if (!key) return subject;
+  if (!IDEMPOTENCY_KEY_RE.test(key)) {
+    throw new Error("Invalid idempotency key: expected 8-200 chars of A-Za-z0-9._:-");
+  }
+  return `${subject}\n\n${IDEMPOTENCY_TRAILER}: ${key}`;
 }
 
 export type FileWrite = {

package/dist/chunk-VAOW4WXQ.js

@@ -1,15 +0,0 @@
-// src/storage/types.ts
-var StorageConflictError = class extends Error {
-  constructor(currentVersion) {
-    super("Draft has been modified since it was loaded");
-    this.currentVersion = currentVersion;
-    this.name = "StorageConflictError";
-  }
-  currentVersion;
-};
-var ASSET_CACHE_CONTROL = "max-age=31536000, immutable";
-
-export {
-  StorageConflictError,
-  ASSET_CACHE_CONTROL
-};

package/dist/{chunk-ABV7OZB3.js → chunk-CS2ECR3U.js}

@@ -7,12 +7,12 @@ import {
 import {
   getSectionSchema
 } from "./chunk-TZQPOR5A.js";
-import {
-  IndexSchema
-} from "./chunk-RHWWQV3J.js";
 import {
   getAllSchemas
 } from "./chunk-VKAGMEKE.js";
+import {
+  IndexSchema
+} from "./chunk-RHWWQV3J.js";
 import {
   MAX_BLOCK_DEPTH,
   blockDepth

package/dist/{chunk-ZKGMLLUQ.js → chunk-IFCQWC3G.js}

@@ -27,13 +27,13 @@ import {
 import {
   cn
 } from "./chunk-7EOSDFS3.js";
+import {
+  defineSection
+} from "./chunk-VKAGMEKE.js";
 import {
   HexColorSchema,
   SingleMediaReferenceSchema
 } from "./chunk-RHWWQV3J.js";
-import {
-  defineSection
-} from "./chunk-VKAGMEKE.js";
 
 // src/components/sections/Colors/index.tsx
 import { z as z2 } from "zod";