@drawnagency/primitives 0.1.114 → 0.1.116

package/src/lib/image-variant-plan.ts

@@ -0,0 +1,92 @@
+import { sanitizeMediaName } from "../media/utils";
+import type { MediaConfig, MediaItem, Variant } from "../schemas/media";
+
+// The one place an uploaded image's identity, storage folder, variant widths,
+// variant paths and manifest entry are decided. Two pixel adapters sit behind
+// it: the editor's OffscreenCanvas worker (media/worker.ts) and the sharp path
+// (authoring processImageBuffers, which the MCP connector calls). They used to
+// build all of this separately and agree only because a comment said so; the
+// site's media settings and dedup each drifted between them once. Pure and
+// browser-safe — the worker imports it.
+
+export interface MediaIdentity {
+  id: string;
+  hash: string;
+  originalName: string;
+  /** Storage dir under assets/images/. Never changes once committed. */
+  folder: string;
+}
+
+/** `hash` is the 16-hex content hash both sides compute (hashFileBuffer / hashBuffer). */
+export function mediaIdentity(hash: string, fileName: string): MediaIdentity {
+  const originalName = sanitizeMediaName(fileName);
+  return { id: hash, hash, originalName, folder: `${originalName}-${hash}` };
+}
+
+/** Repo path of one stored file in a media folder: a variant width, or `poster`. */
+export function imageVariantPath(folder: string, key: number | string): string {
+  return `assets/images/${folder}/${key}.webp`;
+}
+
+export interface ImageVariantPlan extends MediaIdentity {
+  width: number;
+  height: number;
+  /** WebP quality, 1-100. */
+  quality: number;
+  /** Ascending by width. */
+  variants: { width: number; path: string }[];
+}
+
+export function planImageVariants(input: {
+  hash: string;
+  fileName: string;
+  width: number;
+  height: number;
+  media: Pick<MediaConfig, "sizes" | "quality">;
+}): ImageVariantPlan {
+  const identity = mediaIdentity(input.hash, input.fileName);
+  // Never upscale; an image narrower than every configured size still gets one
+  // variant, at its own width.
+  const widths = input.media.sizes.filter((s) => s <= input.width).sort((a, b) => a - b);
+  if (widths.length === 0) widths.push(input.width);
+  return {
+    ...identity,
+    width: input.width,
+    height: input.height,
+    quality: input.media.quality,
+    variants: widths.map((width) => ({ width, path: imageVariantPath(identity.folder, width) })),
+  };
+}
+
+export type ImageManifestEntry = Omit<MediaItem, "kind" | "storage" | "url" | "duration" | "folderId" | "hidden"> & {
+  kind: "image";
+  storage: "github";
+};
+
+/**
+ * `rendered` is what the adapter measured for each planned width (heights come
+ * from the encoder, not the plan). `size` is the adapter's byte count for the
+ * item: the editor records its largest variant, the sharp path the original's
+ * length — they differ today and this module does not decide that.
+ */
+export function imageManifestEntry(plan: ImageVariantPlan, rendered: Variant[], size: number): ImageManifestEntry {
+  const variants = plan.variants.map(({ width }) => {
+    const out = rendered.find((r) => r.width === width);
+    if (!out) throw new Error(`[image-variant-plan] no rendered variant for planned width ${width}`);
+    return { width, height: out.height, size: out.size };
+  });
+  return {
+    id: plan.id,
+    hash: plan.hash,
+    kind: "image",
+    originalName: plan.originalName,
+    width: plan.width,
+    height: plan.height,
+    mimeType: "image/webp",
+    size,
+    folder: plan.folder,
+    variants,
+    alt: "",
+    storage: "github",
+  };
+}

package/src/lib/index-ops.ts

@@ -1,11 +1,12 @@
 import { z } from "zod";
 import { IndexSchema, PageStatusSchema, RESERVED_SLUGS, SLUG_RE, type SiteIndex, type SectionMeta } from "../schemas/site-config";
-import type { NavEntry, NavGroupEntry } from "../schemas/nav";
+import type { NavGroupEntry } from "../schemas/nav";
 import type { NavLocation } from "./nav-tree";
 // Page and nav mutations are shared with the editor rather than reimplemented:
 // both surfaces must agree on what "delete a page" or "remove a group" means, and
 // a second implementation here is how they would drift.
 import { addPage as addPageToIndex, deletePage, slugifyPageSlug, uniquePageSlug } from "./pages";
+import { liftSidecars } from "./sidecars";
 import {
   addGroup, deleteGroup, groupOfPage, moveNavEntry, navEntries, reconcileNav,
   renameGroup, setGroupStartCollapsed,
@@ -254,11 +255,12 @@ export function applyIndexOps(
     };
   }
 
-  // IndexSchema strips `nav` (that strip is what keeps the sidecar out of
-  // index.json), so the authored nav has to be lifted off the RAW input to be
-  // available to the nav ops below. reconcileNav is total, so an unparseable
-  // shape here degrades to a flat nav rather than failing.
-  const rawNav = (rawIndex as { nav?: unknown } | null | undefined)?.nav;
+  // IndexSchema strips `nav` (that strip is what keeps the Sidecar out of
+  // index.json), so the authored nav is lifted off the RAW input to be
+  // available to the nav ops below — as fresh entries, so no op can mutate the
+  // caller's index. reconcileNav is total, so an unreadable nav degrades to a
+  // flat one rather than failing.
+  const lifted = liftSidecars(rawIndex);
 
   // Own copy: the caller's index is also its knownSiteTypes source and may be
   // logged, so nothing here mutates it. Reassigned by the page/nav ops, which
@@ -267,18 +269,7 @@ export function applyIndexOps(
     ...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 }])),
-    // COPIED, not aliased. Taking the caller's array by reference meant any nav
-    // op that spliced in place would mutate the caller's index — the one thing
-    // this function's own comment promises it never does.
-    ...(Array.isArray(rawNav)
-      ? {
-          nav: (rawNav as NavEntry[]).map((entry) =>
-            entry && typeof entry === "object" && "pageIds" in entry
-              ? { ...entry, pageIds: [...(entry as { pageIds: string[] }).pageIds] }
-              : { ...entry },
-          ),
-        }
-      : {}),
+    ...(lifted.nav ? { nav: lifted.nav.entries } : {}),
   };
 
   const removed = new Set<string>();

package/src/lib/index.ts

@@ -5,6 +5,20 @@ export { resolveChatbotName, resolveThinkingPhrases, DEFAULT_CHATBOT_NAME } from
 export { generateNavLinks, toSectionId, type NavItem } from "./nav";
 export { navEntries, pagesInNavOrder, groupOfPage, groupDisplayLabel, reconcileNav } from "./nav-tree";
 export { siteTags, tagDisplayLabel, reconcileTags } from "./tags";
+export {
+  NAV,
+  TAGS,
+  SIDECARS,
+  readSidecar,
+  readSidecarText,
+  liftSidecars,
+  planSidecarWrite,
+  type SidecarDefinition,
+  type SidecarFileState,
+  type SidecarWritePlan,
+  type SidecarRead,
+  type SidecarDiagnostic,
+} from "./sidecars";
 export { resolveReference, type ReferenceContent } from "./references";
 export { REFERENCE_TYPE } from "./reference-type";
 export {
@@ -46,4 +60,5 @@ export {
   loadStaticSiteContent,
   type LoadedSection,
   type SiteContent,
+  type SidecarReads,
 } from "./loader";

package/src/lib/loader.ts

@@ -3,8 +3,9 @@ import { IndexSchema, type SiteIndex, type SectionMeta } from "../schemas/site-c
 import { getAllSchemas } from "./registry";
 import { blockDepth, MAX_BLOCK_DEPTH } from "../schemas/block";
 import { upgradeLegacySection } from "./migrate-sections-transform";
-import { NavEntrySchema, type NavEntry } from "../schemas/nav";
-import { TagEntrySchema, type TagEntry } from "../schemas/tags";
+import type { NavEntry } from "../schemas/nav";
+import type { TagEntry } from "../schemas/tags";
+import type { SidecarRead } from "./sidecars";
 
 export interface LoadedSection {
   section: Section;
@@ -17,11 +18,9 @@ export interface LoadedSection {
 export interface SiteContent {
   sections: LoadedSection[];
   index: SiteIndex;
-  /** True when nav.json was present but held entries this package version could
-   *  not represent (unknown kinds, invalid shapes) — the returned nav is missing
-   *  them. Writers must treat a degraded nav as read-only: wholesale-replacing
-   *  nav.json from a degraded read permanently destroys the entries this
-   *  version dropped. */
+  /** A Degraded read of nav.json (see SidecarRead): the returned nav is missing
+   *  entries, so writers treat it as read-only — wholesale-replacing nav.json
+   *  from it permanently destroys the entries this version dropped. */
   navDegraded: boolean;
   /** Same contract as navDegraded, for tags.json: a degraded read is
    *  read-only for tags. */
@@ -29,68 +28,13 @@ export interface SiteContent {
 }
 
 /**
- * Parse the nav.json sidecar defensively, entry by entry. A malformed sidecar
- * must degrade, never brick the site — nav.json is optional content, and the
- * whole point of the sidecar is that it tolerates writers that don't understand
- * it. Tolerance is PER ENTRY: one unknown entry kind (a newer package version's
- * addition, or an authoring typo) drops that entry alone, not every group on
- * the site. Any drop is reported as `degraded` so write paths can refuse to
- * persist the lossy tree back over the original.
+ * The Sidecars a load read, from the Sidecar module's readers. A Sidecar the
+ * load did not look for is omitted. Tags then stay unattached ("not loaded":
+ * writers leave tags.json alone, where an attached `[]` saved back would delete
+ * every tag). Nav is attached as `[]` either way — the editor has no nav gate
+ * yet to make "not loaded" safe for nav (exploration B).
  */
-function parseNavFile(navFile: unknown): { entries: NavEntry[]; degraded: boolean } {
-  if (!navFile) return { entries: [], degraded: false };
-  const rawEntries = (navFile as { entries?: unknown }).entries;
-  if (!Array.isArray(rawEntries)) {
-    console.warn("[loader] Invalid nav.json, falling back to a flat navigation");
-    return { entries: [], degraded: true };
-  }
-  const entries: NavEntry[] = [];
-  let dropped = 0;
-  for (const raw of rawEntries) {
-    const result = NavEntrySchema.safeParse(raw);
-    if (result.success) entries.push(result.data);
-    else dropped++;
-  }
-  if (dropped > 0) {
-    console.warn(`[loader] nav.json: dropped ${dropped} entr${dropped === 1 ? "y" : "ies"} this package version cannot represent; navigation is degraded`);
-  }
-  return { entries, degraded: dropped > 0 };
-}
-
-/**
- * Parse the tags.json sidecar with parseNavFile's per-entry tolerance and the
- * same `degraded` contract. Assignments to deleted sections are NOT pruned
- * here — that is reconcileTags' job on every read (siteTags), so the runtime
- * field stays a faithful copy of the file.
- */
-function parseTagsFile(tagsFile: unknown): { tags: TagEntry[]; degraded: boolean } {
-  if (!tagsFile) return { tags: [], degraded: false };
-  const rawTags = (tagsFile as { tags?: unknown }).tags;
-  if (!Array.isArray(rawTags)) {
-    console.warn("[loader] Invalid tags.json, falling back to no tags");
-    return { tags: [], degraded: true };
-  }
-  const tags: TagEntry[] = [];
-  let dropped = 0;
-  for (const raw of rawTags) {
-    const result = TagEntrySchema.safeParse(raw);
-    if (result.success) tags.push(result.data);
-    else dropped++;
-  }
-  if (dropped > 0) {
-    console.warn(`[loader] tags.json: dropped ${dropped} entr${dropped === 1 ? "y" : "ies"} this package version cannot represent; tags are degraded`);
-  }
-  return { tags, degraded: dropped > 0 };
-}
-
-/**
- * Whether a load looked for tags.json. Not loaded ⇒ no `index.tags` is attached
- * and writers leave the file alone; loaded ⇒ `file` is its parsed contents,
- * with null/undefined meaning absent (an empty registry). Unlike nav, the
- * difference is load-bearing — an attached `[]` that a writer saves back
- * deletes every tag — hence an explicit flag rather than undefined-vs-null.
- */
-export type TagsSidecar = { loaded: false } | { loaded: true; file: unknown };
+export type SidecarReads = { nav?: SidecarRead<NavEntry>; tags?: SidecarRead<TagEntry> };
 
 /**
  * Merge a validated index with raw section file contents.
@@ -100,8 +44,7 @@ export type TagsSidecar = { loaded: false } | { loaded: true; file: unknown };
 export function mergeSiteContent(
   index: SiteIndex,
   sectionFiles: Record<string, unknown>,
-  navFile?: unknown,
-  tagsSidecar: TagsSidecar = { loaded: false },
+  sidecars: SidecarReads = {},
 ): SiteContent {
   const sections: LoadedSection[] = [];
 
@@ -154,12 +97,11 @@ export function mergeSiteContent(
     }
   }
 
-  const nav = parseNavFile(navFile);
-  const tags = tagsSidecar.loaded ? parseTagsFile(tagsSidecar.file) : null;
+  const { nav, tags } = sidecars;
   return {
     sections,
-    index: { ...index, nav: nav.entries, ...(tags ? { tags: tags.tags } : {}) },
-    navDegraded: nav.degraded,
+    index: { ...index, nav: nav?.entries ?? [], ...(tags ? { tags: tags.entries } : {}) },
+    navDegraded: nav?.degraded ?? false,
     tagsDegraded: tags?.degraded ?? false,
   };
 }
@@ -172,8 +114,7 @@ export function mergeSiteContent(
 export function loadStaticSiteContent(
   index: SiteIndex,
   sectionGlob: Record<string, unknown>,
-  navFile?: unknown,
-  tagsSidecar: TagsSidecar = { loaded: false },
+  sidecars: SidecarReads = {},
 ): SiteContent {
   const sectionFiles: Record<string, unknown> = {};
   for (const [path, data] of Object.entries(sectionGlob)) {
@@ -181,5 +122,5 @@ export function loadStaticSiteContent(
     const id = filename.replace(".json", "");
     sectionFiles[id] = data;
   }
-  return mergeSiteContent(index, sectionFiles, navFile, tagsSidecar);
+  return mergeSiteContent(index, sectionFiles, sidecars);
 }

package/src/lib/media-ops.ts

@@ -0,0 +1,112 @@
+import type { MediaItem, MediaManifest } from "../schemas/media";
+import type { DocumentManifest, DocumentManifestEntry } from "../schemas/documents";
+
+// Media intents (CONTEXT.md: Index op / Media intent): a change to the media
+// library stated as what to do, applied by the write path to its own fresh read
+// of the manifests. A writer that sent a whole manifest instead could only
+// send back what it had read — dropping another writer's images, or `folders`,
+// the moment its copy was stale. Intents leave everything they do not name as
+// the branch has it. Pure: the write path does the reads and the commit.
+
+export type MediaBlob = { path: string; base64: string };
+
+export type MediaOp =
+  /**
+   * A new image and its variant files, keyed by its id (the content hash).
+   * `alt` is the caller's alt text, if it sent one — the only alt applied when
+   * the image turns out to be in the library already (`entry.alt` is just the
+   * new entry's default).
+   */
+  | { op: "addImage"; entry: MediaItem; blobs: MediaBlob[]; alt?: string }
+  | { op: "setImageAlt"; imageId: string; alt: string }
+  | { op: "deleteImage"; imageId: string }
+  /**
+   * A document's manifest entry, with its bytes when they ride in the commit
+   * (git tier; bucket-tier bytes are uploaded beforehand). For an id already in
+   * the library — git-tier ids are the content hash, so the same bytes — only
+   * the filename is applied: its stored bytes and path stay. That is how a
+   * rename lands.
+   */
+  | { op: "putDocument"; documentId: string; entry: DocumentManifestEntry; blob?: MediaBlob };
+
+/**
+ * Per op, in order. `existed` means `addImage` found the image already in the
+ * library: its bytes are not committed again, and only a differing alt text is
+ * applied.
+ */
+export type MediaOpOutcome = "added" | "existed" | "updated" | "deleted";
+
+export type AppliedMediaOps = {
+  ok: true;
+  images: MediaManifest;
+  /** Null when no op touched documents, so the write leaves that file alone. */
+  documents: DocumentManifest | null;
+  uploads: { item: { id: string; folder: string }; blobs: MediaBlob[] }[];
+  /** Images whose variant folders the write deletes. */
+  deletions: { id: string; folder: string }[];
+  outcomes: MediaOpOutcome[];
+};
+
+export function applyMediaOps(
+  manifests: { images: MediaManifest; documents: DocumentManifest },
+  ops: MediaOp[],
+): AppliedMediaOps | { ok: false; code: "not_found"; error: string } {
+  const images: MediaManifest = { ...manifests.images, images: { ...manifests.images.images } };
+  let documents: DocumentManifest | null = null;
+  const uploads: AppliedMediaOps["uploads"] = [];
+  const deletions: AppliedMediaOps["deletions"] = [];
+  const outcomes: MediaOpOutcome[] = [];
+
+  // Keys are content hashes and normally equal the entry's id; find by id so a
+  // caller naming the id it was given always reaches the right entry.
+  const keyOf = (imageId: string) =>
+    imageId in images.images ? imageId : Object.keys(images.images).find((key) => images.images[key].id === imageId);
+  const notFound = (imageId: string) =>
+    ({ ok: false, code: "not_found", error: `No media with imageId "${imageId}" in the site's media library.` }) as const;
+
+  for (const op of ops) {
+    switch (op.op) {
+      case "addImage": {
+        const key = keyOf(op.entry.id);
+        if (key === undefined) {
+          images.images[op.entry.id] = op.entry;
+          uploads.push({ item: { id: op.entry.id, folder: op.entry.folder }, blobs: op.blobs });
+          outcomes.push("added");
+        } else {
+          if (op.alt !== undefined) images.images[key] = { ...images.images[key], alt: op.alt };
+          outcomes.push("existed");
+        }
+        break;
+      }
+      case "setImageAlt": {
+        const key = keyOf(op.imageId);
+        if (key === undefined) return notFound(op.imageId);
+        images.images[key] = { ...images.images[key], alt: op.alt };
+        outcomes.push("updated");
+        break;
+      }
+      case "deleteImage": {
+        const key = keyOf(op.imageId);
+        if (key === undefined) return notFound(op.imageId);
+        deletions.push({ id: key, folder: images.images[key].folder });
+        delete images.images[key];
+        outcomes.push("deleted");
+        break;
+      }
+      case "putDocument": {
+        documents ??= { ...manifests.documents };
+        const existing = documents[op.documentId];
+        if (existing) {
+          documents[op.documentId] = { ...existing, filename: op.entry.filename };
+          outcomes.push(existing.filename === op.entry.filename ? "existed" : "updated");
+        } else {
+          documents[op.documentId] = op.entry;
+          if (op.blob) uploads.push({ item: { id: op.documentId, folder: op.blob.path.split("/")[2] ?? "" }, blobs: [op.blob] });
+          outcomes.push("added");
+        }
+        break;
+      }
+    }
+  }
+  return { ok: true, images, documents, uploads, deletions, outcomes };
+}

package/src/lib/nav-tree.ts

@@ -1,5 +1,6 @@
 import type { NavEntry, NavGroupEntry } from "../schemas/nav";
 import type { Page, SiteIndex } from "../schemas/site-config";
+import { diagnosticsCollector, type SidecarDiagnostic } from "./sidecar-diagnostics";
 
 /**
  * Repair an authored nav against the current page set.
@@ -19,6 +20,15 @@ import type { Page, SiteIndex } from "../schemas/site-config";
  * prior state and defeat identity-based re-render checks.
  */
 export function reconcileNav(entries: NavEntry[], pages: Page[]): NavEntry[] {
+  return reconcileNavReport(entries, pages).entries;
+}
+
+/** reconcileNav plus what the repair changed — what a validator reports. */
+export function reconcileNavReport(
+  entries: NavEntry[],
+  pages: Page[],
+): { entries: NavEntry[]; diagnostics: SidecarDiagnostic[] } {
+  const report = diagnosticsCollector();
   const entryList = Array.isArray(entries) ? entries : [];
   const pageList = Array.isArray(pages) ? pages : [];
 
@@ -33,7 +43,14 @@ export function reconcileNav(entries: NavEntry[], pages: Page[]): NavEntry[] {
 
   for (const entry of entryList) {
     if (entry?.kind === "page") {
-      if (!validIds.has(entry.pageId) || placed.has(entry.pageId)) continue;
+      if (!validIds.has(entry.pageId)) {
+        report.add("dangling", entry.pageId);
+        continue;
+      }
+      if (placed.has(entry.pageId)) {
+        report.add("duplicate-member", entry.pageId);
+        continue;
+      }
       placed.add(entry.pageId);
       result.push({ ...entry });
       continue;
@@ -46,12 +63,23 @@ export function reconcileNav(entries: NavEntry[], pages: Page[]): NavEntry[] {
     // and "total" would be a lie. Dropping it spills its members to the tail
     // append below: a group lost, never a page.
     if (typeof entry.id !== "string" || entry.id === "") continue;
-    if (seenGroupIds.has(entry.id)) continue;
+    if (seenGroupIds.has(entry.id)) {
+      report.add("duplicate-id", entry.id);
+      continue;
+    }
     seenGroupIds.add(entry.id);
 
     const claimed = Array.isArray(entry.pageIds) ? entry.pageIds : [];
     const pageIds = claimed.filter((id) => {
-      if (typeof id !== "string" || !validIds.has(id) || placed.has(id)) return false;
+      if (typeof id !== "string") return false;
+      if (!validIds.has(id)) {
+        report.add("dangling", id);
+        return false;
+      }
+      if (placed.has(id)) {
+        report.add("duplicate-member", id);
+        return false;
+      }
       placed.add(id);
       return true;
     });
@@ -70,10 +98,11 @@ export function reconcileNav(entries: NavEntry[], pages: Page[]): NavEntry[] {
   for (const p of pageList) {
     if (!p?.id || placed.has(p.id)) continue;
     placed.add(p.id);
+    report.add("unlisted", p.id);
     result.push({ kind: "page", pageId: p.id });
   }
 
-  return result;
+  return { entries: result, diagnostics: report.list() };
 }
 
 /**

package/src/lib/pages.ts

@@ -5,6 +5,7 @@ import { RESERVED_SLUGS } from "../schemas/site-config";
 // block (mirrors the same sanctioned import in schemas/site-config.ts).
 import { documentOptionsSchema, type DocumentOptions } from "../document/engine/settings";
 import { navEntries } from "./nav-tree";
+import { slugifyPageSlug } from "./slug";
 
 /**
  * Display fallback for blank page titles. addPage creates pages with an empty
@@ -15,9 +16,7 @@ export function pageDisplayTitle(title: string): string {
   return title || "Untitled";
 }
 
-export function slugifyPageSlug(input: string): string {
-  return input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
-}
+export { slugifyPageSlug };
 
 export function uniquePageSlug(base: string, existing: string[]): string {
   const taken = new Set(existing);