@drawnagency/primitives 0.1.114 → 0.1.116

package/src/lib/site-validation.ts

@@ -0,0 +1,269 @@
+import type { ZodType } from "zod";
+import { IndexSchema, SiteConfigSchema, type SiteIndex } from "../schemas/site-config";
+import { ImageManifestSchema } from "../schemas/media";
+import { DOCUMENT_MANIFEST_PATH, DocumentManifestSchema } from "../schemas/documents";
+import { NAV, TAGS, readSidecarText, type SidecarDefinition, type SidecarDiagnostic } from "./sidecars";
+import { checkSection } from "./section-check";
+import { upgradeLegacySection } from "./migrate-sections-transform";
+import { collectImageIds } from "./image-refs";
+import { collectDocumentIds } from "./document-refs";
+import { referenceProblems, type ReferenceProblem } from "./reference-validation";
+
+const INDEX_PATH = "src/content/index.json";
+const SITE_CONFIG_PATH = "src/content/site-config.json";
+const IMAGE_MANIFEST_PATH = "src/content/image-manifest.json";
+const sectionPath = (id: string): string => `src/content/sections/${id}.json`;
+
+/** What the caller can vouch for. Never how severe anything is — that is SEVERITY. */
+export interface SiteValidationPolicy {
+  /**
+   * A section type with no registered schema: `trust` reads it as a real type
+   * this caller cannot check (the connector, whose branch index is the proof; a
+   * CLI whose site sections module failed to load), `reject` as an unknown type.
+   */
+  unregisteredTypes: "trust" | "reject";
+}
+
+export interface SchemaIssue {
+  path: readonly PropertyKey[];
+  message: string;
+}
+
+type ProblemBody =
+  | { code: "index-missing" }
+  | { code: "index-invalid"; detail: string }
+  | { code: "site-id-empty" }
+  | { code: "site-config-missing" }
+  | { code: "site-config-invalid"; detail: string }
+  | { code: "sidecar-degraded"; sidecar: "nav" | "tags" }
+  | { code: "sidecar-repaired"; sidecar: "nav" | "tags"; diagnostic: SidecarDiagnostic }
+  | { code: "image-manifest-invalid"; detail: string }
+  | { code: "document-manifest-invalid"; detail: string }
+  | { code: "section-missing"; sectionId: string }
+  | { code: "section-unparseable"; sectionId: string; detail: string }
+  | { code: "section-id-mismatch"; sectionId: string; fileId: unknown }
+  | { code: "section-type-mismatch"; sectionId: string; fileType: unknown; indexType: string }
+  | { code: "unknown-type"; sectionId: string; type: string }
+  | { code: "unvalidated-type"; sectionId: string; type: string }
+  | { code: "section-invalid"; sectionId: string; type: string; issues: SchemaIssue[] }
+  | { code: "layout-invalid"; sectionId: string; issues: SchemaIssue[] }
+  | { code: "too-deep"; sectionId: string }
+  | { code: "reference-in-container"; sectionId: string }
+  | { code: "html-entities"; sectionId: string; path: string; entities: string[] }
+  | { code: "dangling-image"; sectionId: string; imageId: string }
+  | { code: "dangling-document"; sectionId: string; documentId: string }
+  | { code: "reference-problem"; problem: ReferenceProblem };
+
+export type SiteProblemCode = ProblemBody["code"];
+export type Severity = "error" | "warning";
+export type SiteProblem = ProblemBody & { severity: Severity };
+
+/**
+ * The one severity table every caller shares. An ERROR is something the site
+ * cannot load, or authored content it silently loses or rejects. A WARNING is
+ * something the site renders through — dropping or repairing it itself — and
+ * that is fixable in-product, so it must not fail a build.
+ */
+export const SEVERITY: Readonly<Record<SiteProblemCode, Severity>> = {
+  "index-missing": "error",
+  "index-invalid": "error",
+  "site-id-empty": "error",
+  "site-config-missing": "error",
+  "site-config-invalid": "error",
+  // The loader drops what it cannot read, so authored grouping or tags vanish.
+  "sidecar-degraded": "error",
+  // What reconcile repairs on every load: the runtime has already fixed it.
+  "sidecar-repaired": "warning",
+  "image-manifest-invalid": "error",
+  "document-manifest-invalid": "error",
+  "section-missing": "error",
+  "section-unparseable": "error",
+  "section-id-mismatch": "error",
+  "section-type-mismatch": "error",
+  "unknown-type": "error",
+  "unvalidated-type": "warning",
+  "section-invalid": "error",
+  "layout-invalid": "error",
+  "too-deep": "error",
+  "reference-in-container": "error",
+  "html-entities": "warning",
+  "dangling-image": "warning",
+  "dangling-document": "warning",
+  "reference-problem": "warning",
+};
+
+export interface SiteValidation {
+  problems: SiteProblem[];
+  /** The section ids the index places on pages; null when the index could not be read. */
+  placedIds: string[] | null;
+}
+
+function parseJson(text: string): { ok: true; value: unknown } | { ok: false; detail: string } {
+  try {
+    return { ok: true, value: JSON.parse(text) };
+  } catch (e) {
+    return { ok: false, detail: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+/** The text parsed and schema-checked, or why it could not be. */
+function parseFile<T>(text: string, schema: ZodType<T>): { ok: true; data: T } | { ok: false; detail: string } {
+  const json = parseJson(text);
+  if (!json.ok) return json;
+  const parsed = schema.safeParse(json.value);
+  return parsed.success ? { ok: true, data: parsed.data } : { ok: false, detail: parsed.error.message };
+}
+
+/**
+ * Validate a site's committed content. `files` maps repo paths under
+ * `src/content/` to their text; an absent path is an absent file. Pure: it reads
+ * the schema registry, so callers register built-in (and any site-local)
+ * schemas first. Only sections the index places on a page are judged — orphan
+ * files are the caller's concern.
+ */
+export function validateSite(files: Readonly<Record<string, string>>, policy: SiteValidationPolicy): SiteValidation {
+  const problems: SiteProblem[] = [];
+  const report = (body: ProblemBody) => problems.push({ ...body, severity: SEVERITY[body.code] });
+
+  const indexText = files[INDEX_PATH];
+  if (indexText === undefined) {
+    report({ code: "index-missing" });
+    return { problems, placedIds: null };
+  }
+  const indexRead = parseFile(indexText, IndexSchema);
+  if (!indexRead.ok) {
+    report({ code: "index-invalid", detail: indexRead.detail });
+    return { problems, placedIds: null };
+  }
+  const index: SiteIndex = indexRead.data;
+  const placedIds = [...new Set(index.pages.flatMap((p) => p.order))];
+
+  if (!index.siteId) report({ code: "site-id-empty" });
+
+  const configText = files[SITE_CONFIG_PATH];
+  if (configText === undefined) {
+    report({ code: "site-config-missing" });
+  } else {
+    const configRead = parseFile(configText, SiteConfigSchema);
+    if (!configRead.ok) report({ code: "site-config-invalid", detail: configRead.detail });
+  }
+
+  const checkSidecar = <E>(def: SidecarDefinition<E>): E[] | null => {
+    const text = files[def.path];
+    if (text === undefined) return [];
+    const read = readSidecarText(def, text);
+    if (read.degraded) {
+      report({ code: "sidecar-degraded", sidecar: def.name });
+      return null;
+    }
+    for (const diagnostic of def.reconcile(read.entries, index).diagnostics) {
+      report({ code: "sidecar-repaired", sidecar: def.name, diagnostic });
+    }
+    return read.entries;
+  };
+  checkSidecar(NAV);
+  // The tag ids a Reference may name: none when the file is absent, unknown
+  // (null, so tag ids go unchecked) when it cannot be read in full.
+  const tags = checkSidecar(TAGS);
+  const tagIds = tags === null ? null : new Set(tags.map((t) => t.id));
+
+  // The ids in each manifest; null when it is present but unreadable — nothing
+  // can be judged against a manifest we could not read, and reporting every
+  // reference as dangling would bury the one diagnostic that matters. Absent is
+  // the normal state of a site with nothing uploaded: an empty manifest.
+  let imageIds: Set<string> | null = new Set();
+  const imageText = files[IMAGE_MANIFEST_PATH];
+  if (imageText !== undefined) {
+    const read = parseFile(imageText, ImageManifestSchema);
+    if (read.ok) imageIds = new Set(Object.keys(read.data.images));
+    else {
+      report({ code: "image-manifest-invalid", detail: read.detail });
+      imageIds = null;
+    }
+  }
+  let documentIds: Set<string> | null = new Set();
+  const documentText = files[DOCUMENT_MANIFEST_PATH];
+  if (documentText !== undefined) {
+    const read = parseFile(documentText, DocumentManifestSchema);
+    if (read.ok) documentIds = new Set(Object.keys(read.data));
+    else {
+      report({ code: "document-manifest-invalid", detail: read.detail });
+      documentIds = null;
+    }
+  }
+
+  const bodies: { id: string; content: unknown }[] = [];
+  for (const id of placedIds) {
+    const text = files[sectionPath(id)];
+    if (text === undefined) {
+      report({ code: "section-missing", sectionId: id });
+      continue;
+    }
+    const json = parseJson(text);
+    if (!json.ok) {
+      report({ code: "section-unparseable", sectionId: id, detail: json.detail });
+      continue;
+    }
+    const onDisk = (typeof json.value === "object" && json.value !== null ? json.value : {}) as Record<string, unknown>;
+    if (onDisk.id !== id) report({ code: "section-id-mismatch", sectionId: id, fileId: onDisk.id });
+    // Retired types are rewritten at every load before the site validates them,
+    // so validate what the site runs, by the type it runs as.
+    const body = upgradeLegacySection(json.value);
+    bodies.push({ id, content: body });
+    const upgradedType = typeof body === "object" && body !== null ? (body as { type?: unknown }).type : undefined;
+    const type = typeof upgradedType === "string" ? upgradedType : "";
+
+    // The index may name either form of a legacy section: the retired type
+    // both still hold, or the type it upgrades to once a writer has reconciled
+    // the index. Either renders; only an index type matching neither is wrong.
+    const indexType = index.sections[id].type;
+    if (indexType !== onDisk.type && indexType !== upgradedType) {
+      report({ code: "section-type-mismatch", sectionId: id, fileType: onDisk.type, indexType });
+    }
+    // A body with no type has just been reported as a mismatch; there is no
+    // type to judge it by, and "unknown type \"\"" would say nothing more.
+    if (type === "") continue;
+
+    const check = checkSection(type, body);
+    if (check.unregistered) {
+      if (policy.unregisteredTypes === "reject") {
+        report({ code: "unknown-type", sectionId: id, type });
+      } else {
+        report({ code: "unvalidated-type", sectionId: id, type });
+        if (check.error?.code === "depth") report({ code: "too-deep", sectionId: id });
+      }
+    } else if (check.error) {
+      const error = check.error;
+      switch (error.code) {
+        case "schema":
+          report({ code: "section-invalid", sectionId: id, type, issues: error.zodError.issues });
+          break;
+        case "layout":
+          report({ code: "layout-invalid", sectionId: id, issues: error.zodError.issues });
+          break;
+        case "depth":
+          report({ code: "too-deep", sectionId: id });
+          break;
+        case "reference-in-container":
+          report({ code: "reference-in-container", sectionId: id });
+          break;
+      }
+    }
+    for (const { path, entities } of check.entities) report({ code: "html-entities", sectionId: id, path, entities });
+
+    if (imageIds) {
+      for (const imageId of collectImageIds(body)) {
+        if (!imageIds.has(imageId)) report({ code: "dangling-image", sectionId: id, imageId });
+      }
+    }
+    if (documentIds) {
+      for (const documentId of collectDocumentIds(body)) {
+        if (!documentIds.has(documentId)) report({ code: "dangling-document", sectionId: id, documentId });
+      }
+    }
+  }
+
+  for (const problem of referenceProblems(bodies, index, tagIds)) report({ code: "reference-problem", problem });
+
+  return { problems, placedIds };
+}

package/src/lib/slug.ts

@@ -0,0 +1,6 @@
+// The one slugifier for page slugs and media names. Its own leaf, with no
+// imports, so the media worker can use it without bundling the schemas
+// lib/pages pulls in.
+export function slugifyPageSlug(input: string): string {
+  return input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}

package/src/lib/storage-tier.ts

@@ -0,0 +1,38 @@
+import { DOCUMENT_GIT_MAX_BYTES, DOCUMENT_BUCKET_MAX_BYTES } from "../schemas/documents";
+import { MEDIA_GIT_MAX_BYTES, MEDIA_BUCKET_MAX_BYTES, type MediaConfig } from "../schemas/media";
+
+// Where a file's bytes live, decided by its size: committed to the site repo
+// (git), stored in the optional bucket, or refused. Every upload path and the
+// write path's backstop decide this the same way, and every message quotes the
+// limits through formatBytes, so a limit changes in one place.
+
+export { DOCUMENT_GIT_MAX_BYTES, DOCUMENT_BUCKET_MAX_BYTES, MEDIA_GIT_MAX_BYTES, MEDIA_BUCKET_MAX_BYTES };
+
+/**
+ * The MCP connector's own document ceiling, half the bucket cap. The binding
+ * constraint is memory, not time: a presigned PUT cannot stream, so the whole
+ * body is buffered (peak about 2x the file). The browser path has no such
+ * limit because those bytes never pass through a function.
+ */
+export const DOCUMENT_CONNECTOR_MAX_BYTES = 104_857_600;
+
+export type StorageTier = "git" | "bucket" | "too_large";
+
+type MediaLimits = Pick<MediaConfig, "maxFileSize" | "maxAssetSize">;
+
+/** Media limits come from the site's `media` config; documents' are fixed. */
+export function tierFor(
+  kind: "document" | "media",
+  bytes: number,
+  media: MediaLimits = { maxFileSize: MEDIA_GIT_MAX_BYTES, maxAssetSize: MEDIA_BUCKET_MAX_BYTES },
+): StorageTier {
+  const [gitMax, bucketMax] =
+    kind === "document" ? [DOCUMENT_GIT_MAX_BYTES, DOCUMENT_BUCKET_MAX_BYTES] : [media.maxFileSize, media.maxAssetSize];
+  if (bytes <= gitMax) return "git";
+  return bytes <= bucketMax ? "bucket" : "too_large";
+}
+
+/** "2.5 MB", "100 MB" — one decimal at most, in binary megabytes. */
+export function formatBytes(bytes: number): string {
+  return `${Math.round((bytes / 1024 / 1024) * 10) / 10} MB`;
+}

package/src/lib/tags.ts

@@ -1,5 +1,6 @@
 import type { TagEntry } from "../schemas/tags";
 import type { SiteIndex } from "../schemas/site-config";
+import { diagnosticsCollector, type SidecarDiagnostic } from "./sidecar-diagnostics";
 
 /**
  * Repair the tag sidecar against the current section set.
@@ -19,6 +20,15 @@ import type { SiteIndex } from "../schemas/site-config";
  * React state, where a shared array would let a later edit mutate prior state).
  */
 export function reconcileTags(entries: TagEntry[], sections: SiteIndex["sections"]): TagEntry[] {
+  return reconcileTagsReport(entries, sections).entries;
+}
+
+/** reconcileTags plus what the repair changed — what a validator reports. */
+export function reconcileTagsReport(
+  entries: TagEntry[],
+  sections: SiteIndex["sections"],
+): { entries: TagEntry[]; diagnostics: SidecarDiagnostic[] } {
+  const report = diagnosticsCollector();
   const entryList = Array.isArray(entries) ? entries : [];
   const validIds = new Set(sections && typeof sections === "object" ? Object.keys(sections) : []);
 
@@ -26,17 +36,24 @@ export function reconcileTags(entries: TagEntry[], sections: SiteIndex["sections
   const result: TagEntry[] = [];
   for (const entry of entryList) {
     if (!entry || typeof entry !== "object") continue;
-    if (typeof entry.id !== "string" || entry.id === "" || seenTagIds.has(entry.id)) continue;
+    if (typeof entry.id !== "string" || entry.id === "") continue;
+    if (seenTagIds.has(entry.id)) {
+      report.add("duplicate-id", entry.id);
+      continue;
+    }
     seenTagIds.add(entry.id);
 
     const claimed = Array.isArray(entry.sectionIds) ? entry.sectionIds : [];
     const sectionIds: string[] = [];
     for (const id of claimed) {
-      if (typeof id === "string" && validIds.has(id) && !sectionIds.includes(id)) sectionIds.push(id);
+      if (typeof id !== "string") continue;
+      if (!validIds.has(id)) report.add("dangling", id);
+      else if (sectionIds.includes(id)) report.add("duplicate-member", id);
+      else sectionIds.push(id);
     }
     result.push({ id: entry.id, label: typeof entry.label === "string" ? entry.label : "", sectionIds });
   }
-  return result;
+  return { entries: result, diagnostics: report.list() };
 }
 
 /**

package/src/media/queue.ts

@@ -1,4 +1,5 @@
 import type { MediaKind } from "./types";
+import type { ImageVariantPlan } from "../lib/image-variant-plan";
 
 export interface QueueInput {
   buffer: ArrayBuffer;
@@ -23,6 +24,7 @@ export interface QueueItem {
     posterBlob?: Blob;
     width: number;
     height: number;
+    plan?: ImageVariantPlan;
   };
 }
 
@@ -116,6 +118,7 @@ export class ProcessingQueue {
           posterBlob: msg.posterBlob,
           width: msg.width,
           height: msg.height,
+          plan: msg.plan,
         };
         this.options.onEvent({ type: "complete", item: { ...item } });
         // The event above carries the only reference anyone reads. Holding ours

package/src/media/utils.ts

@@ -1,4 +1,4 @@
-import { slugifyPageSlug } from "../lib/pages";
+import { slugifyPageSlug } from "../lib/slug";
 import type { MediaItem } from "./types";
 
 export async function hashFileBuffer(buffer: ArrayBuffer): Promise<string> {

package/src/media/worker.ts

@@ -1,3 +1,5 @@
+import { planImageVariants, type ImageVariantPlan } from "../lib/image-variant-plan";
+
 interface ProcessMessage {
   type: "process";
   id: string;
@@ -24,6 +26,8 @@ interface CompleteMessage {
   posterBlob?: Blob;
   width: number;
   height: number;
+  /** Static images only — the shared plan the variants were rendered from. */
+  plan?: ImageVariantPlan;
 }
 
 interface ErrorMessage {
@@ -77,13 +81,17 @@ self.onmessage = async (e: MessageEvent<ProcessMessage>) => {
 
     post({ type: "progress", id: msg.id, percent: 25 });
 
-    const applicableSizes = msg.sizes
-      .filter((s) => s <= origWidth)
-      .sort((a, b) => b - a);
-
-    if (applicableSizes.length === 0) {
-      applicableSizes.push(origWidth);
-    }
+    // Widths, names and paths come from the shared plan (the sharp path uses
+    // the same one); this worker only draws. Encoded largest first so the
+    // primary blob is the largest variant.
+    const plan = planImageVariants({
+      hash: msg.hash,
+      fileName: msg.originalName,
+      width: origWidth,
+      height: origHeight,
+      media: { sizes: msg.sizes, quality: msg.quality },
+    });
+    const applicableSizes = plan.variants.map((v) => v.width).reverse();
 
     const variants: { width: number; height: number; size: number; blob: Blob }[] = [];
     const totalVariants = applicableSizes.length;
@@ -97,7 +105,7 @@ self.onmessage = async (e: MessageEvent<ProcessMessage>) => {
       const ctx = canvas.getContext("2d")!;
       ctx.drawImage(bitmap, 0, 0, targetWidth, targetHeight);
 
-      const blob = await canvas.convertToBlob({ type: "image/webp", quality: msg.quality / 100 });
+      const blob = await canvas.convertToBlob({ type: "image/webp", quality: plan.quality / 100 });
       variants.push({ width: targetWidth, height: targetHeight, size: blob.size, blob });
 
       const percent = 25 + Math.round(((i + 1) / totalVariants) * 75);
@@ -114,6 +122,7 @@ self.onmessage = async (e: MessageEvent<ProcessMessage>) => {
       primaryBlob,
       width: origWidth,
       height: origHeight,
+      plan,
     });
   } catch (err) {
     const message = err instanceof Error ? err.message : "Processing failed";

package/src/schemas/media.ts

@@ -55,13 +55,18 @@ export const ImageManifestSchema = z.object({
 
 export type MediaManifest = z.infer<typeof ImageManifestSchema>;
 
+/** Default git-tier cap for media (bytes); a site may override it as `media.maxFileSize`. */
+export const MEDIA_GIT_MAX_BYTES = 5_242_880;
+/** Default bucket-tier cap for media (bytes); a site may override it as `media.maxAssetSize`. */
+export const MEDIA_BUCKET_MAX_BYTES = 209_715_200;
+
 export const MediaConfigSchema = z.object({
   sizes: z.array(z.number()).default([640, 1080, 1920]),
-  maxFileSize: z.number().default(5242880),
+  maxFileSize: z.number().default(MEDIA_GIT_MAX_BYTES),
   quality: z.number().min(1).max(100).default(85),
   // Per-file cap for bucket-backed video uploads (bytes). The git-path cap is
   // maxFileSize; anything between the two routes to the AssetStore.
-  maxAssetSize: z.number().default(209_715_200),
+  maxAssetSize: z.number().default(MEDIA_BUCKET_MAX_BYTES),
 });
 
 export type MediaConfig = z.infer<typeof MediaConfigSchema>;

package/src/storage/memory.ts

@@ -0,0 +1,178 @@
+import {
+  IDEMPOTENCY_TRAILER,
+  NothingToPublishError,
+  StorageConflictError,
+  type FileWrite,
+  type StorageProvider,
+} from "./types";
+
+// An in-memory StorageProvider with real commit history: a `main` branch, an
+// optional draft branch, and commits addressable by sha. It exists so the write
+// path can be tested end to end without mocking it, which is only worth
+// anything if it behaves like the GitHub adapter — the storage contract suite
+// runs the same cases against both. Anything that differs from GitHub here is a
+// bug in this file.
+
+type Tree = Map<string, Uint8Array>;
+type Commit = { tree: Tree; parent: string | null; message: string };
+type Files = Record<string, string | Uint8Array | null>;
+
+// Mirrors promoteDraft in the GitHub adapter: only these subtrees publish;
+// everything else on main is inherited from main.
+const PUBLISHED_PREFIXES = ["src/content/", "assets/"];
+
+export type MemoryStorage = StorageProvider & {
+  /**
+   * Commit straight to a branch as another writer would — a concurrent editor
+   * save on the draft (created from main if absent), or a merge onto main.
+   * Returns the new commit's sha.
+   */
+  commit(branch: "main" | "draft", files: Files, message?: string): string;
+  /**
+   * Run `fn` once at the start of the next `writeFiles`, before its
+   * `baseVersion` check: a writer landing between a caller's read and its write.
+   */
+  beforeNextWrite(fn: () => void): void;
+};
+
+export function createMemoryStorage(seed: { main?: Files; draft?: Files } = {}): MemoryStorage {
+  const commits = new Map<string, Commit>();
+  let counter = 0;
+  let mainHead: string;
+  let draftHead: string | null = null;
+  let pendingHook: (() => void) | null = null;
+
+  function newCommit(tree: Tree, parent: string | null, message: string): string {
+    counter += 1;
+    const sha = counter.toString(16).padStart(40, "0");
+    commits.set(sha, { tree, parent, message });
+    return sha;
+  }
+
+  function applyFiles(base: Tree, files: Files): Tree {
+    const tree = new Map(base);
+    for (const [path, content] of Object.entries(files)) {
+      if (content === null) tree.delete(path);
+      else tree.set(path, toBytes(content));
+    }
+    return tree;
+  }
+
+  function commitTo(branch: "main" | "draft", files: Files, message = "commit"): string {
+    if (branch === "main") {
+      mainHead = newCommit(applyFiles(commits.get(mainHead)!.tree, files), mainHead, message);
+      return mainHead;
+    }
+    const parent = draftHead ?? mainHead;
+    draftHead = newCommit(applyFiles(commits.get(parent)!.tree, files), parent, message);
+    return draftHead;
+  }
+
+  // Unknown branch or sha reads as absent, as GitHub's 404 does.
+  function treeFor(options?: { draft?: boolean; at?: string }): Tree | null {
+    if (options?.at !== undefined) return commits.get(options.at)?.tree ?? null;
+    if (options?.draft) return draftHead === null ? null : commits.get(draftHead)!.tree;
+    return commits.get(mainHead)!.tree;
+  }
+
+  function checkBase(options?: { baseVersion?: string | null }): void {
+    if (options && "baseVersion" in options) {
+      const expected = options.baseVersion ?? null;
+      if (expected !== draftHead) throw new StorageConflictError(draftHead);
+    }
+  }
+
+  mainHead = newCommit(applyFiles(new Map(), seed.main ?? {}), null, "initial");
+  if (seed.draft) commitTo("draft", seed.draft, "seed draft");
+
+  return {
+    commit: commitTo,
+
+    beforeNextWrite(fn) {
+      pendingHook = fn;
+    },
+
+    async writeFiles(files: FileWrite[], message: string, options?: { baseVersion?: string | null }) {
+      const hook = pendingHook;
+      pendingHook = null;
+      hook?.();
+
+      checkBase(options);
+      if (files.length === 0) return { version: draftHead ?? mainHead };
+
+      const parentTree = commits.get(draftHead ?? mainHead)!.tree;
+      const changes: Files = {};
+      for (const file of files) {
+        // GitHub's createTree rejects deleting a path its base tree does not hold.
+        if (file.content === null && !parentTree.has(file.path)) {
+          throw new Error(`Cannot delete ${file.path}: it is not on the branch`);
+        }
+        changes[file.path] =
+          file.content === null || file.content instanceof Uint8Array || file.encoding !== "base64"
+            ? file.content
+            : fromBase64(file.content);
+      }
+      return { version: commitTo("draft", changes, message) };
+    },
+
+    async readFile(path, options) {
+      return treeFor(options)?.get(path) ?? null;
+    },
+
+    async listDirectory(path, options) {
+      const tree = treeFor(options);
+      if (!tree) return [];
+      const prefix = path.endsWith("/") ? path : `${path}/`;
+      const names: string[] = [];
+      for (const key of tree.keys()) {
+        if (!key.startsWith(prefix)) continue;
+        const rest = key.slice(prefix.length);
+        if (!rest.includes("/")) names.push(rest);
+      }
+      return names;
+    },
+
+    async getVersion() {
+      return mainHead;
+    },
+
+    async getDraftVersion() {
+      return draftHead;
+    },
+
+    async promoteDraft() {
+      if (draftHead === null) throw new NothingToPublishError();
+      const draft = commits.get(draftHead)!.tree;
+      const main = commits.get(mainHead)!.tree;
+      const published = (p: string) => PUBLISHED_PREFIXES.some((prefix) => p.startsWith(prefix));
+      if (![...draft.keys(), ...main.keys()].some(published)) {
+        throw new Error("No editor-managed content found on the saved branch — refusing to publish.");
+      }
+      const tree = new Map([...main].filter(([p]) => !published(p)));
+      for (const [p, bytes] of draft) if (published(p)) tree.set(p, bytes);
+      mainHead = newCommit(tree, mainHead, "Publish content via Brand Portal");
+      draftHead = null;
+      return { version: mainHead };
+    },
+
+    async findCommitByIdempotencyKey(key, options) {
+      const limit = Math.min(Math.max(options?.limit ?? 30, 1), 100);
+      const trailer = `${IDEMPOTENCY_TRAILER}: ${key}`;
+      let sha = draftHead;
+      for (let seen = 0; sha !== null && seen < limit; seen += 1) {
+        const commit = commits.get(sha)!;
+        if (commit.message.split("\n").some((line) => line.trim() === trailer)) return sha;
+        sha = commit.parent;
+      }
+      return null;
+    },
+  };
+}
+
+function toBytes(content: string | Uint8Array): Uint8Array {
+  return typeof content === "string" ? new TextEncoder().encode(content) : content;
+}
+
+function fromBase64(content: string): Uint8Array {
+  return Uint8Array.from(atob(content), (c) => c.charCodeAt(0));
+}