@drawnagency/primitives 0.1.94 → 0.1.96

package/src/lib/history-buckets.ts

@@ -0,0 +1,190 @@
+export interface HistoryCommit {
+  sha: string;
+  date: string;
+  /** First parent's sha; null for the repo's root commit. */
+  parent: string | null;
+}
+
+export type NodeKind = "commit" | "day" | "week" | "month" | "year";
+
+export interface HistoryNode {
+  /** Stable React key, unique within the tree. */
+  id: string;
+  kind: NodeKind;
+  label: string;
+  sublabel: string | null;
+  count: number;
+  /** Newest commit in this node — what "browse" opens. */
+  newestSha: string | null;
+  /** Compare base: parent of this node's oldest commit. Null at repo root. */
+  baseSha: string | null;
+  children: HistoryNode[];
+}
+
+export type GroupId =
+  | "today" | "this-week" | "previous-weeks" | "earlier-months" | "previous-years";
+
+export interface HistoryGroup {
+  id: GroupId;
+  label: string;
+  nodes: HistoryNode[];
+}
+
+const GROUPS: { id: GroupId; label: string }[] = [
+  { id: "today", label: "Today" },
+  { id: "this-week", label: "Earlier this week" },
+  { id: "previous-weeks", label: "Previous weeks" },
+  { id: "earlier-months", label: "Earlier months" },
+  { id: "previous-years", label: "Previous years" },
+];
+
+// Calendar-day arithmetic (not fixed-ms) so DST transitions don't shift boundaries.
+const startOfDay = (d: Date) => new Date(d.getFullYear(), d.getMonth(), d.getDate());
+const addDays = (d: Date, n: number) =>
+  new Date(d.getFullYear(), d.getMonth(), d.getDate() + n);
+const startOfYear = (d: Date) => new Date(d.getFullYear(), 0, 1);
+
+const WEEKDAY = new Intl.DateTimeFormat(undefined, { weekday: "long" });
+const MONTH = new Intl.DateTimeFormat(undefined, { month: "long" });
+const MON_DAY = new Intl.DateTimeFormat(undefined, { month: "short", day: "numeric" });
+const TIME = new Intl.DateTimeFormat(undefined, { hour: "numeric", minute: "2-digit" });
+
+interface Dated extends HistoryCommit {
+  at: Date;
+}
+
+/** Oldest-first list → node metadata shared by every non-commit node. */
+function rollup(sorted: Dated[]): Pick<HistoryNode, "count" | "newestSha" | "baseSha"> {
+  return {
+    count: sorted.length,
+    newestSha: sorted.length ? sorted[sorted.length - 1].sha : null,
+    baseSha: sorted.length ? sorted[0].parent : null,
+  };
+}
+
+function commitNode(c: Dated): HistoryNode {
+  return {
+    id: `c:${c.sha}`,
+    kind: "commit",
+    label: TIME.format(c.at),
+    sublabel: null,
+    count: 1,
+    newestSha: c.sha,
+    baseSha: c.parent,
+    children: [],
+  };
+}
+
+/** Bucket by a key derived from each commit's date, newest bucket first. */
+function bucketBy(sorted: Dated[], key: (d: Date) => string): Map<string, Dated[]> {
+  const out = new Map<string, Dated[]>();
+  for (const c of sorted) {
+    const k = key(c.at);
+    const list = out.get(k);
+    if (list) list.push(c);
+    else out.set(k, [c]);
+  }
+  // sorted is oldest-first, so reverse the insertion order for newest-first display.
+  return new Map([...out.entries()].reverse());
+}
+
+const dayKey = (d: Date) => `${d.getFullYear()}-${d.getMonth()}-${d.getDate()}`;
+const monthKey = (d: Date) => `${d.getFullYear()}-${d.getMonth()}`;
+const yearKey = (d: Date) => `${d.getFullYear()}`;
+
+/** Day nodes whose children are commit nodes. `weekday` picks the label style. */
+function dayNodes(sorted: Dated[], weekday: boolean): HistoryNode[] {
+  return [...bucketBy(sorted, dayKey).entries()].map(([k, list]) => ({
+    id: `d:${k}`,
+    kind: "day" as const,
+    label: weekday ? WEEKDAY.format(list[0].at) : MON_DAY.format(list[0].at),
+    sublabel: weekday ? MON_DAY.format(list[0].at) : null,
+    ...rollup(list),
+    children: [...list].reverse().map(commitNode),
+  }));
+}
+
+function monthNodes(sorted: Dated[], withYear: boolean): HistoryNode[] {
+  return [...bucketBy(sorted, monthKey).entries()].map(([k, list]) => ({
+    id: `m:${k}`,
+    kind: "month" as const,
+    label: MONTH.format(list[0].at),
+    sublabel: withYear ? String(list[0].at.getFullYear()) : null,
+    ...rollup(list),
+    children: dayNodes(list, false),
+  }));
+}
+
+function yearNodes(sorted: Dated[]): HistoryNode[] {
+  return [...bucketBy(sorted, yearKey).entries()].map(([k, list]) => ({
+    id: `y:${k}`,
+    kind: "year" as const,
+    label: k,
+    sublabel: null,
+    ...rollup(list),
+    children: monthNodes(list, false),
+  }));
+}
+
+/**
+ * Up to three 7-day windows, newest first. Windows with no commits are dropped
+ * rather than rendered empty — an editor scanning history wants the edits, not
+ * a fixed-width calendar.
+ */
+function weekNodes(sorted: Dated[], windowStart: Date): HistoryNode[] {
+  const out: HistoryNode[] = [];
+  for (let i = 1; i <= 3; i++) {
+    const start = addDays(windowStart, -7 * i);
+    const end = addDays(windowStart, -7 * (i - 1));
+    const list = sorted.filter((c) => c.at >= start && c.at < end);
+    if (list.length === 0) continue;
+    out.push({
+      id: `w:${dayKey(start)}`,
+      kind: "week",
+      label: `${MON_DAY.format(start)} – ${MON_DAY.format(addDays(end, -1))}`,
+      sublabel: null,
+      ...rollup(list),
+      children: dayNodes(list, false),
+    });
+  }
+  return out;
+}
+
+export function buildHistoryTree(commits: HistoryCommit[], now: Date): HistoryGroup[] {
+  // Oldest-first throughout; each builder reverses for display.
+  const sorted: Dated[] = commits
+    .map((c) => ({ ...c, at: new Date(c.date) }))
+    .filter((c) => !Number.isNaN(c.at.getTime()))
+    .sort((a, b) => a.at.getTime() - b.at.getTime());
+
+  const t0 = startOfDay(now);          // today begins
+  const t1 = addDays(t0, -6);          // "earlier this week" window begins
+  const t2 = addDays(t1, -21);         // "previous weeks" window begins
+  const y0 = startOfYear(now);         // current year begins
+  const monthsEnd = t2;                // earlier-months covers [y0, t2)
+  const yearsEnd = t2 < y0 ? t2 : y0;  // previous-years covers [-inf, yearsEnd)
+
+  const inRange = (lo: Date | null, hi: Date) =>
+    sorted.filter((c) => (lo === null || c.at >= lo) && c.at < hi);
+
+  const byId: Record<GroupId, HistoryNode[]> = {
+    "today": [...sorted.filter((c) => c.at >= t0)].reverse().map(commitNode),
+    "this-week": dayNodes(inRange(t1, t0), true),
+    "previous-weeks": weekNodes(sorted, t1),
+    "earlier-months": monthsEnd > y0 ? monthNodes(inRange(y0, monthsEnd), true) : [],
+    "previous-years": yearNodes(inRange(null, yearsEnd)),
+  };
+
+  return GROUPS.map((g) => ({ ...g, nodes: byId[g.id] }));
+}
+
+/** Largest node count anywhere in the tree; never 0, so callers can divide by it. */
+export function maxNodeCount(groups: HistoryGroup[]): number {
+  let max = 1;
+  const walk = (n: HistoryNode) => {
+    if (n.count > max) max = n.count;
+    n.children.forEach(walk);
+  };
+  groups.forEach((g) => g.nodes.forEach(walk));
+  return max;
+}

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/lib/index.ts

@@ -12,7 +12,7 @@ export {
   suggestAccessibleOn,
   type WcagLevel,
 } from "./contrast";
-export { primaryVarValue, accentVarValue } from "./theme-vars";
+export { primaryVarValue, accentVarValue, onPrimaryVarValue } from "./theme-vars";
 export { sanitizeHtml, ensureSanitizer } from "./sanitize";
 export { gridColsClass } from "./grid";
 export { getIcon, curatedIcons, type IconEntry } from "./icons";

package/src/lib/media-folders.ts

@@ -178,6 +178,22 @@ export function healMediaManifest(manifest: MediaManifest): MediaManifest {
   return { ...manifest, images, folders };
 }
 
+/**
+ * Rebase a local manifest onto a freshly-fetched remote one, so media another
+ * writer added is in our copy before the next save assembles from it. Without
+ * this a rebased session still writes its pre-conflict manifest, which silently
+ * drops their entries and orphans the files they committed.
+ *
+ * Images union, ours winning, so local alt/folder-move edits survive; a pending
+ * local deletion isn't removed from the manifest until save, so the union can't
+ * resurrect one. Folders stay ours verbatim — deleting a folder removes it from
+ * our map with no wire signal, so unioning would undo the delete. Mirrors the
+ * server-side merge in core's content-ops.
+ */
+export function rebaseMediaManifest(local: MediaManifest, remote: MediaManifest): MediaManifest {
+  return { ...local, images: { ...remote.images, ...local.images } };
+}
+
 /**
  * Save-time manifest assembly: merge uploaded pending items, apply deletions,
  * preserve every other manifest key (folders!), then heal.

package/src/lib/registry.ts

@@ -77,12 +77,20 @@ export type Thumbnail =
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type CustomSettingsFormProps = Record<string, any>;
 
+export interface ModalOptions {
+  /** Content is a tab set — lock the modal height so tab switches don't resize it. */
+  tabbed?: boolean;
+}
+
+/** Signature of the editor's modal opener as threaded down to sections. */
+export type OpenModal = (title: string, content: ReactNode, options?: ModalOptions) => void;
+
 export interface SectionProps<T = unknown> {
   content: T;
   options?: Record<string, unknown>;
   onChange?: (content: T) => void;
   isEditMode: boolean;
-  openModal?: (title: string, content: ReactNode) => void;
+  openModal?: OpenModal;
   /** Delete this whole section. Used e.g. when a colors section's last swatch
    *  is dragged into another section, leaving it empty. */
   onDelete?: () => void;

package/src/lib/theme-vars.ts

@@ -1,11 +1,13 @@
 import type { SiteConfig } from "../schemas/site-config";
+import { suggestAccessibleOn } from "./contrast";
 
 /**
  * Computes the CSS value for the brand `--color-primary` / `--color-primary-contrast`
- * custom properties. When darkMode is "optional" AND a dark variant is set, the
- * value is a CSS `light-dark(<light>, <dark>)` expression — the browser resolves
- * it per the element's `color-scheme` (the `.dark` class sets `color-scheme: dark`;
- * `:root` sets `color-scheme: light`). Otherwise it's the plain light hex.
+ * / `--color-on-primary` custom properties. When darkMode is "optional" AND a dark
+ * variant is set, the value is a CSS `light-dark(<light>, <dark>)` expression — the
+ * browser resolves it per the element's `color-scheme` (the `.dark` class sets
+ * `color-scheme: dark`; `:root` sets `color-scheme: light`). Otherwise it's the
+ * plain light hex.
  *
  * Single source of truth for every injection site: Layout.astro / LoginLayout.astro
  * (SSR inline `<html style>`) and EditorShell (live setProperty + localStorage).
@@ -29,3 +31,22 @@ export function primaryVarValue(c?: Partial<ThemeColorConfig> | null): string {
 export function accentVarValue(c?: Partial<ThemeColorConfig> | null): string {
   return lightDark(c?.primaryContrast ?? DEFAULT_CONTRAST, c?.primaryContrastDark, c?.darkMode === "optional");
 }
+
+/**
+ * Foreground ink for text drawn ON a `--color-primary`-filled surface (branded
+ * plates, primary cards). Derived from `primaryColor` with the same
+ * black/white WCAG pick the editor's accent "Suggest" button uses, so a
+ * primary-filled surface is legible on every brand without configuration.
+ *
+ * This exists because `--color-primary-contrast` cannot serve the role: it is
+ * the *accent* — brands legitimately repoint it at a decorative colour (Siete's
+ * gold on aubergine) that reads as a highlight but cannot carry body copy.
+ * Sections should consume `var(--color-on-primary)` for text on primary and
+ * keep `--color-primary-contrast` for accents, and derive softer inks by mixing
+ * the two brand tokens: `color-mix(in srgb, var(--color-on-primary) 70%, var(--color-primary))`.
+ */
+export function onPrimaryVarValue(c?: Partial<ThemeColorConfig> | null): string {
+  const light = suggestAccessibleOn(c?.primaryColor ?? DEFAULT_PRIMARY);
+  const dark = c?.primaryColorDark ? suggestAccessibleOn(c.primaryColorDark) : null;
+  return lightDark(light, dark, c?.darkMode === "optional");
+}

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 = {