@drawnagency/primitives 0.1.56 → 0.1.58

package/src/lib/block-move.ts

@@ -0,0 +1,236 @@
+import type { LoadedSection } from "./loader";
+import type { Section } from "../schemas/sections";
+import type { SiteIndex, SectionMeta } from "../schemas/site-config";
+import { ROOT_CONTAINER_ID, canDropBlock } from "./block-dnd";
+import { getContainerChildren, reorderChild, insertChildAt, removeChildAt, placeBlockAtColumn, trimTrailingSpacers } from "./container-ops";
+import { reorderSectionInPage, addSectionToPage, removeSectionFromPages } from "./pages";
+
+export interface BlockMoveState {
+  sections: LoadedSection[];
+  index: SiteIndex;
+  rootPageId: string;
+}
+
+export interface BlockMove {
+  blockId: string;
+  fromContainerId: string;
+  fromIndex: number;
+  toContainerId: string;
+  /** Raw insertion index in the ORIGINAL (pre-removal) array, 0..len — as resolveDropIndex returns. applyBlockMove shifts it for same-container moves. */
+  toIndex: number;
+  /** When set, place at this 1-based grid column (ghost/spacer drop) instead of toIndex. */
+  toColumn?: number;
+}
+
+export interface BlockMoveEffects {
+  markDirtySectionIds: string[];
+  indexDirty: boolean;
+  deleteSectionIds: string[];
+  createSectionIds: string[];
+}
+
+export interface BlockMoveResult {
+  sections: LoadedSection[];
+  index: SiteIndex;
+  effects: BlockMoveEffects;
+  changed: boolean;
+}
+
+function defaultNewId(): string {
+  return typeof crypto !== "undefined" && typeof crypto.randomUUID === "function"
+    ? crypto.randomUUID()
+    : `block-${Math.random().toString(36).slice(2)}`;
+}
+
+const DEFAULT_CHILD_META = (type: string): SectionMeta => ({ type, status: "draft", access: [] });
+
+function isContainerSection(section: Section): boolean {
+  return Array.isArray((section.content as { children?: unknown })?.children);
+}
+
+function mapContainerSection(sections: LoadedSection[], id: string, fn: (s: Section) => Section): LoadedSection[] {
+  return sections.map((l) => (l.section.id === id ? { ...l, section: fn(l.section) } : l));
+}
+
+function noop(state: BlockMoveState): BlockMoveResult {
+  return {
+    sections: state.sections,
+    index: state.index,
+    effects: { markDirtySectionIds: [], indexDirty: false, deleteSectionIds: [], createSectionIds: [] },
+    changed: false,
+  };
+}
+
+export function applyBlockMove(
+  state: BlockMoveState,
+  move: BlockMove,
+  newId: () => string = defaultNewId,
+): BlockMoveResult {
+  const { sections, index, rootPageId } = state;
+  const { blockId, fromContainerId, fromIndex, toContainerId, toIndex } = move;
+
+  if (move.toColumn != null) return applyColumnPlacement(state, move, newId);
+
+  const draggedSection = findBlock(sections, fromContainerId, fromIndex, blockId);
+  if (!draggedSection) return noop(state);
+  const dragData = {
+    dragType: "block" as const,
+    blockId,
+    containerId: fromContainerId,
+    index: fromIndex,
+    isContainer: isContainerSection(draggedSection),
+  };
+  if (!canDropBlock(dragData, toContainerId)) return noop(state);
+
+  if (fromContainerId === toContainerId) {
+    // toIndex is the raw insertion index in the original (pre-removal) array.
+    // Both reorderSectionInPage and reorderChild use splice(from,1)+splice(to,0,moved),
+    // so we must convert to the post-removal position for same-container moves.
+    const adjusted = fromIndex < toIndex ? toIndex - 1 : toIndex;
+    if (fromContainerId === ROOT_CONTAINER_ID) {
+      const nextIndex = reorderSectionInPage(index, rootPageId, fromIndex, adjusted);
+      if (nextIndex === index) return noop(state);
+      return {
+        sections,
+        index: nextIndex,
+        effects: { markDirtySectionIds: [], indexDirty: true, deleteSectionIds: [], createSectionIds: [] },
+        changed: true,
+      };
+    }
+    const nextSections = mapContainerSection(sections, fromContainerId, (c) => reorderChild(c, fromIndex, adjusted));
+    return {
+      sections: nextSections,
+      index,
+      effects: { markDirtySectionIds: [fromContainerId], indexDirty: false, deleteSectionIds: [], createSectionIds: [] },
+      changed: true,
+    };
+  }
+
+  const markDirty = new Set<string>();
+  const deleteSectionIds: string[] = [];
+  const createSectionIds: string[] = [];
+  let indexDirty = false;
+  let nextSections = sections;
+  let nextIndex = index;
+
+  let moving: Section;
+  if (fromContainerId === ROOT_CONTAINER_ID) {
+    moving = draggedSection;
+    nextSections = nextSections.filter((l) => l.section.id !== blockId);
+    nextIndex = removeSectionFromPages(nextIndex, blockId);
+    deleteSectionIds.push(blockId);
+    indexDirty = true;
+  } else {
+    const src = nextSections.find((l) => l.section.id === fromContainerId);
+    if (!src) return noop(state);
+    const { container, removed } = removeChildAt(src.section, fromIndex);
+    if (!removed) return noop(state);
+    moving = removed;
+    nextSections = mapContainerSection(nextSections, fromContainerId, () => container);
+    markDirty.add(fromContainerId);
+  }
+
+  if (toContainerId === ROOT_CONTAINER_ID) {
+    const { layout: _dropLayout, ...rootBlock } = moving as Section & { layout?: unknown };
+    const meta = DEFAULT_CHILD_META(rootBlock.type);
+    nextIndex = addSectionToPage(nextIndex, rootPageId, rootBlock.id, meta, toIndex);
+    nextSections = [...nextSections, { section: rootBlock as Section, meta }];
+    indexDirty = true;
+    createSectionIds.push(rootBlock.id);
+    markDirty.add(rootBlock.id);
+  } else {
+    const dest = nextSections.find((l) => l.section.id === toContainerId);
+    if (!dest) return noop(state);
+    nextSections = mapContainerSection(nextSections, toContainerId, (c) => insertChildAt(c, moving, toIndex));
+    markDirty.add(toContainerId);
+  }
+
+  return {
+    sections: nextSections,
+    index: nextIndex,
+    effects: { markDirtySectionIds: [...markDirty], indexDirty, deleteSectionIds, createSectionIds },
+    changed: true,
+  };
+}
+
+/**
+ * Column-targeted placement (a ghost/spacer drop). Removes the dragged block from its source
+ * (root or a container), then places it at 1-based column `toColumn` of the destination
+ * container — padding intervening empty columns with spacers, or replacing a spacer already at
+ * that column. Root is never a column target (it has no columns).
+ */
+function applyColumnPlacement(
+  state: BlockMoveState,
+  move: BlockMove,
+  newId: () => string,
+): BlockMoveResult {
+  const { sections, index } = state;
+  const { blockId, fromContainerId, fromIndex, toContainerId } = move;
+  const toColumn = move.toColumn!;
+
+  if (toContainerId === ROOT_CONTAINER_ID) return noop(state);
+
+  const draggedSection = findBlock(sections, fromContainerId, fromIndex, blockId);
+  if (!draggedSection) return noop(state);
+  const dragData = {
+    dragType: "block" as const,
+    blockId,
+    containerId: fromContainerId,
+    index: fromIndex,
+    isContainer: isContainerSection(draggedSection),
+  };
+  if (!canDropBlock(dragData, toContainerId)) return noop(state);
+
+  const markDirty = new Set<string>();
+  const deleteSectionIds: string[] = [];
+  let indexDirty = false;
+  let nextSections = sections;
+  let nextIndex = index;
+  let moving: Section;
+
+  if (fromContainerId === ROOT_CONTAINER_ID) {
+    moving = draggedSection;
+    nextSections = nextSections.filter((l) => l.section.id !== blockId);
+    nextIndex = removeSectionFromPages(nextIndex, blockId);
+    deleteSectionIds.push(blockId);
+    indexDirty = true;
+  } else {
+    const src = nextSections.find((l) => l.section.id === fromContainerId);
+    if (!src) return noop(state);
+    const { container, removed } = removeChildAt(src.section, fromIndex);
+    if (!removed) return noop(state);
+    moving = removed;
+    nextSections = mapContainerSection(nextSections, fromContainerId, () => trimTrailingSpacers(container));
+    markDirty.add(fromContainerId);
+  }
+
+  const dest = nextSections.find((l) => l.section.id === toContainerId);
+  if (!dest) return noop(state);
+  const columns = ((dest.section.content as { columns?: number })?.columns) ?? 1;
+  nextSections = mapContainerSection(nextSections, toContainerId, (c) =>
+    placeBlockAtColumn(c, moving, toColumn, columns, newId),
+  );
+  markDirty.add(toContainerId);
+
+  return {
+    sections: nextSections,
+    index: nextIndex,
+    effects: { markDirtySectionIds: [...markDirty], indexDirty, deleteSectionIds, createSectionIds: [] },
+    changed: true,
+  };
+}
+
+function findBlock(
+  sections: LoadedSection[],
+  containerId: string,
+  index: number,
+  blockId: string,
+): Section | null {
+  if (containerId === ROOT_CONTAINER_ID) {
+    return sections.find((l) => l.section.id === blockId)?.section ?? null;
+  }
+  const host = sections.find((l) => l.section.id === containerId);
+  if (!host) return null;
+  const children = getContainerChildren(host.section);
+  return children[index]?.id === blockId ? children[index] : (children.find((c) => c.id === blockId) ?? null);
+}

package/src/lib/container-grid.ts

@@ -0,0 +1,58 @@
+/** Max columns a container exposes in v1 (covers halves/thirds/sixths via spans). */
+export const MAX_CONTAINER_COLUMNS = 6;
+
+/**
+ * Column count -> grid-cols classes that collapse by the CONTAINER's own width
+ * (Tailwind 4 container-query `@` variants), not the viewport. Full static
+ * strings so Tailwind's source scan generates them (no interpolation/purge gap).
+ */
+export const containerGridClass: Record<number, string> = {
+  1: "grid-cols-1",
+  2: "grid-cols-1 @sm:grid-cols-2",
+  3: "grid-cols-1 @sm:grid-cols-2 @lg:grid-cols-3",
+  4: "grid-cols-1 @xs:grid-cols-2 @lg:grid-cols-4",
+  5: "grid-cols-1 @xs:grid-cols-2 @md:grid-cols-3 @xl:grid-cols-5",
+  6: "grid-cols-1 @xs:grid-cols-2 @md:grid-cols-3 @2xl:grid-cols-6",
+};
+
+/**
+ * Per-child colSpan -> col-span classes, keyed [columns][span]. A child's span
+ * must clamp to the columns AVAILABLE at each container-query breakpoint, and the
+ * collapse curve differs per column count — so the class depends on BOTH the
+ * parent's column count and the child's span, not span alone. At every breakpoint
+ * the emitted span = min(span, columns-at-that-breakpoint), guaranteeing a span
+ * never exceeds the tracks that exist (no phantom column). Span 1 needs no class.
+ * Full static strings so Tailwind's source scan generates them.
+ */
+export const colSpanClass: Record<number, Record<number, string>> = {
+  1: { 1: "" },
+  2: { 1: "", 2: "col-span-1 @sm:col-span-2" },
+  3: { 1: "", 2: "col-span-1 @sm:col-span-2", 3: "col-span-1 @sm:col-span-2 @lg:col-span-3" },
+  4: { 1: "", 2: "col-span-1 @xs:col-span-2", 3: "col-span-1 @xs:col-span-2 @lg:col-span-3", 4: "col-span-1 @xs:col-span-2 @lg:col-span-4" },
+  5: { 1: "", 2: "col-span-1 @xs:col-span-2", 3: "col-span-1 @xs:col-span-2 @md:col-span-3", 4: "col-span-1 @xs:col-span-2 @md:col-span-3 @xl:col-span-4", 5: "col-span-1 @xs:col-span-2 @md:col-span-3 @xl:col-span-5" },
+  6: { 1: "", 2: "col-span-1 @xs:col-span-2", 3: "col-span-1 @xs:col-span-2 @md:col-span-3", 4: "col-span-1 @xs:col-span-2 @md:col-span-3 @2xl:col-span-4", 5: "col-span-1 @xs:col-span-2 @md:col-span-3 @2xl:col-span-5", 6: "col-span-1 @xs:col-span-2 @md:col-span-3 @2xl:col-span-6" },
+};
+
+/** Gap token -> Tailwind gap class. Retained as a utility; the container now uses a
+ *  fixed gap (the Gap setting was removed), but the map stays for general use. */
+export const gapClass: Record<string, string> = {
+  none: "gap-0",
+  sm: "gap-2",
+  md: "gap-4",
+  lg: "gap-8",
+};
+
+/**
+ * Per-column-count container-query classes that HIDE a spacer cell once the container
+ * collapses to a single column (mobile). Mirrors `containerGridClass`'s collapse curve:
+ * hidden at base width, shown at the first breakpoint where the grid has ≥2 columns.
+ * Static strings so Tailwind's source scan generates them.
+ */
+export const spacerHiddenClass: Record<number, string> = {
+  1: "hidden",
+  2: "hidden @sm:block",
+  3: "hidden @sm:block",
+  4: "hidden @xs:block",
+  5: "hidden @xs:block",
+  6: "hidden @xs:block",
+};

package/src/lib/container-ops.ts

@@ -0,0 +1,159 @@
+import type { ReactNode } from "react";
+import type { Section } from "../schemas/sections";
+import { getAllSections } from "./registry";
+
+interface ContainerContent {
+  columns: number;
+  gap: string;
+  flow: string;
+  childDefaults?: Record<string, unknown>;
+  children: Section[];
+}
+
+/** A container is any block whose `content.children` is an array. */
+export function getContainerChildren(block: Section): Section[] {
+  const content = block.content as Partial<ContainerContent> | undefined;
+  return Array.isArray(content?.children) ? (content!.children as Section[]) : [];
+}
+
+function withChildren(container: Section, children: Section[]): Section {
+  return { ...container, content: { ...(container.content as object), children } };
+}
+
+function containerColumns(container: Section): number {
+  const n = (container.content as Partial<ContainerContent>)?.columns;
+  return typeof n === "number" && n >= 1 ? n : 1;
+}
+
+export function reorderChild(container: Section, from: number, to: number): Section {
+  const children = getContainerChildren(container);
+  if (from < 0 || from >= children.length || to < 0 || to >= children.length) return container;
+  const next = [...children];
+  const [moved] = next.splice(from, 1);
+  next.splice(to, 0, moved);
+  return withChildren(container, next);
+}
+
+/**
+ * Block types insertable as a container CHILD — excludes `container` itself
+ * (v1 enforces one level of container nesting). Shared so the depth guard has a
+ * single, testable source of truth (the container toolbar's "+" picker uses it).
+ */
+export function childInsertableTypes(): { type: string; label: string; icon: ReactNode }[] {
+  return getAllSections()
+    .filter((d) => d.type !== "container" && d.type !== "spacer")
+    .map((d) => ({ type: d.type, label: d.label, icon: d.icon }));
+}
+
+export function insertChildAt(container: Section, child: Section, index: number): Section {
+  const children = getContainerChildren(container);
+  const at = Math.max(0, Math.min(index, children.length));
+  const next = [...children];
+  next.splice(at, 0, child);
+  return withChildren(container, next);
+}
+
+export function removeChildAt(
+  container: Section,
+  index: number,
+): { container: Section; removed: Section | null } {
+  const children = getContainerChildren(container);
+  if (index < 0 || index >= children.length) return { container, removed: null };
+  const next = [...children];
+  const [removed] = next.splice(index, 1);
+  return { container: withChildren(container, next), removed };
+}
+
+export function duplicateChildAt(
+  container: Section,
+  index: number,
+  newId: () => string,
+): Section {
+  const children = getContainerChildren(container);
+  if (index < 0 || index >= children.length) return container;
+  const clone = { ...(JSON.parse(JSON.stringify(children[index])) as Section), id: newId() };
+  const next = [...children];
+  next.splice(index + 1, 0, clone);
+  return withChildren(container, next);
+}
+
+/** Set a child's colSpan, clamped to the container's columns. Span 1 removes `layout`. */
+export function setChildColSpan(container: Section, index: number, span: number): Section {
+  const children = getContainerChildren(container);
+  if (index < 0 || index >= children.length) return container;
+  const clamped = Math.max(1, Math.min(span, containerColumns(container)));
+  const next = children.map((child, i) => {
+    if (i !== index) return child;
+    if (clamped <= 1) {
+      const { layout: _drop, ...rest } = child;
+      return rest as Section;
+    }
+    return { ...child, layout: { ...child.layout, colSpan: clamped } };
+  });
+  return withChildren(container, next);
+}
+
+/** Effective grid tracks a child occupies (spacer = 1; real child = clamped colSpan). */
+function effectiveSpan(child: Section, columns: number): number {
+  return isSpacer(child) ? 1 : Math.min(child.layout?.colSpan ?? 1, columns);
+}
+
+/** A spacer is the empty gap-filler block. */
+export function isSpacer(child: Section): boolean {
+  return child.type === "spacer";
+}
+
+/** Mint a fresh empty spacer block. */
+export function makeSpacer(newId: () => string): Section {
+  return { id: newId(), type: "spacer", content: {} };
+}
+
+/** Grid tracks occupied by a container's children (real child = clamped colSpan, spacer = 1). */
+export function occupiedColumns(children: Section[], columns: number): number {
+  return children.reduce((sum, c) => sum + effectiveSpan(c, columns), 0);
+}
+
+/** Remove spacer children after the last non-spacer child (a trailing gap is meaningless). */
+export function trimTrailingSpacers(container: Section): Section {
+  const children = getContainerChildren(container);
+  let end = children.length;
+  while (end > 0 && isSpacer(children[end - 1])) end--;
+  if (end === children.length) return container;
+  return withChildren(container, children.slice(0, end));
+}
+
+/**
+ * Place `block` at 1-based grid column `K` of `container`. If a spacer already holds column
+ * `K`, replace it; otherwise pad intervening empty columns with spacers and append the block.
+ * Trailing spacers are trimmed. `columns` clamps colSpan accounting; `newId` mints spacer ids.
+ *
+ * Precondition: `K` addresses an EMPTY column — a trailing empty column or one held by a
+ * spacer. The editor's drop targets (ghost/spacer cells) only ever address empty columns, so
+ * callers never target a column consumed by a real block. Defensive: out-of-range `K`
+ * (`K < 1 || K > columns`) or a spacer `block` returns the container unchanged. A `block` with
+ * `colSpan > 1` dropped onto a single spacer keeps its span; CSS grid reflows it (v1).
+ */
+export function placeBlockAtColumn(
+  container: Section,
+  block: Section,
+  K: number,
+  columns: number,
+  newId: () => string,
+): Section {
+  if (K < 1 || K > columns) return container;
+  if (isSpacer(block)) return container;
+  const children = getContainerChildren(container);
+  let col = 0;
+  for (let i = 0; i < children.length; i++) {
+    const span = effectiveSpan(children[i], columns);
+    if (isSpacer(children[i]) && K >= col + 1 && K <= col + span) {
+      const next = [...children];
+      next.splice(i, 1, block);
+      return trimTrailingSpacers(withChildren(container, next));
+    }
+    col += span;
+  }
+  const pad = Math.max(0, K - 1 - col);
+  const spacers = Array.from({ length: pad }, () => makeSpacer(newId));
+  return trimTrailingSpacers(withChildren(container, [...children, ...spacers, block]));
+}

package/src/lib/dexie.ts

@@ -142,6 +142,28 @@ class EditorDatabase extends Dexie {
       await tx.table("siteIndex").clear();
       await tx.table("contentCache").clear();
     });
+    // v8: the legacy→container migration (Plan 5 retirement of split_content/
+    // media_grid/do_dont_grid/do_dont). The editor's loadContent prefers the
+    // cached content when its SHA matches, and that path does NOT re-run the
+    // loader fallback — so a cache populated before the package gained
+    // `container` support holds raw legacy sections that the retired registry
+    // can't render ("Unknown section type: media_grid"). Drop the cached
+    // baseline so the editor re-fetches through /api/content →
+    // mergeSiteContent, which upgrades legacy sections to containers.
+    // One-time; re-fetched content is native.
+    this.version(8).stores({
+      sections: "sectionId",
+      siteIndex: "key",
+      meta: "key",
+      siteConfig: "key",
+      contentCache: "key",
+      mediaManifest: "key",
+      pendingMedia: "id",
+      pendingMediaDeletions: "id",
+    }).upgrade(async (tx) => {
+      await tx.table("siteIndex").clear();
+      await tx.table("contentCache").clear();
+    });
   }
 }
 

package/src/lib/loader.ts

@@ -1,6 +1,8 @@
 import { getSectionSchema, type Section } from "../schemas/sections";
 import { IndexSchema, type SiteIndex, type SectionMeta } from "../schemas/site-config";
 import { getAllSchemas } from "./registry";
+import { blockDepth, MAX_BLOCK_DEPTH } from "../schemas/block";
+import { upgradeLegacySection } from "./migrate-sections-transform";
 
 export interface LoadedSection {
   section: Section;
@@ -28,11 +30,19 @@ export function mergeSiteContent(
 
   const orderedIds = index.pages.flatMap((p) => p.order);
   for (const id of orderedIds) {
-    const raw = sectionFiles[id];
-    if (!raw) {
+    const rawFile = sectionFiles[id];
+    if (!rawFile) {
       console.warn(`Section file missing for id: ${id}, skipping`);
       continue;
     }
+    // Transitional upgrade: rewrite legacy-typed JSON to a container BEFORE
+    // validation, so retired/legacy files render on every load path. Returns the
+    // same reference for non-legacy input (idempotent). We normalize the emitted
+    // section's meta.type when an upgrade happens (no mutation of the caller's index).
+    const raw = upgradeLegacySection(rawFile);
+    const baseMeta = index.sections[id];
+    const meta = raw !== rawFile ? { ...baseMeta, type: "container" } : baseMeta;
+
     if (canValidate && schema) {
       const result = schema.safeParse(raw);
       if (!result.success) {
@@ -40,10 +50,12 @@ export function mergeSiteContent(
         console.warn(`Skipping section "${id}" (type: ${type}): invalid schema`);
         continue;
       }
-      const meta = index.sections[id];
+      if (blockDepth(result.data) > MAX_BLOCK_DEPTH) {
+        console.warn(`Skipping section "${id}": block tree depth exceeds ${MAX_BLOCK_DEPTH}`);
+        continue;
+      }
       sections.push({ section: result.data, meta });
     } else {
-      const meta = index.sections[id];
       sections.push({ section: raw as Section, meta });
     }
   }

package/src/lib/migrate-sections-transform.ts

@@ -0,0 +1,147 @@
+/**
+ * Pure, browser-safe transform that rewrites the three legacy "layout-as-content"
+ * section types into the recursive `container` block. Used by BOTH the loader
+ * fallback (mergeSiteContent) and the codemod (scripts/migrate-sections.ts), so
+ * it must stay free of Node APIs and registry/schema imports.
+ *
+ * Structural only — it never sanitizes. Output is emitted in schema-normal form
+ * (every defaulted key explicit, only known ref fields carried) so that
+ * `transform(raw)` deep-equals `safeParse(transform(raw))` (convergence).
+ */
+
+type Obj = Record<string, unknown>;
+
+const RETIRED = new Set(["split_content", "media_grid", "do_dont_grid", "do_dont"]);
+
+export function upgradeLegacySection(raw: unknown): unknown {
+  if (!raw || typeof raw !== "object") return raw;
+  const section = raw as Obj;
+  if (!RETIRED.has(section.type as string)) return raw; // same reference → idempotent
+  if (section.type === "split_content") return upgradeSplitContent(section);
+  if (section.type === "do_dont") return upgradeDoDont(section);
+  return upgradeGrid(section); // media_grid | do_dont_grid (per-item type drives the mapping)
+}
+
+/** Carry only known BaseMediaRef (+ video) fields; drops render artifacts (src/srcset/alt) and any stray keys. */
+function buildRef(item: Obj, forceImage: boolean): Obj {
+  const type = forceImage ? "image" : (item.type as string);
+  const ref: Obj = { type, imageId: item.imageId ?? "" };
+  if (item.caption !== undefined) ref.caption = item.caption;
+  if (item.background !== undefined) ref.background = item.background;
+  if (item.invertFrom !== undefined) ref.invertFrom = item.invertFrom;
+  if (item.border !== undefined) ref.border = item.border;
+  if (item.objectFit !== undefined) ref.objectFit = item.objectFit;
+  if (type === "video") {
+    if (item.poster !== undefined) ref.poster = item.poster;
+    if (item.autoplay !== undefined) ref.autoplay = item.autoplay;
+    if (item.loop !== undefined) ref.loop = item.loop;
+    if (item.muted !== undefined) ref.muted = item.muted;
+  }
+  return ref;
+}
+
+function mapRefItem(item: Obj, parentId: string, index: number): Obj {
+  const content: Obj = {};
+  if (item.type === "linkedImage") {
+    content.ref = buildRef(item, true);
+    content.link = { kind: "external", href: item.href ?? "", target: item.target === "_blank" ? "_blank" : "_self" };
+  } else if (item.type === "doDontImage") {
+    content.ref = buildRef(item, true);
+    if (item.doDont !== undefined) content.dodont = item.doDont;
+  } else {
+    content.ref = buildRef(item, false); // image | video
+  }
+  return { id: `${parentId}__media_${index}`, type: "media", content, options: {} };
+}
+
+function upgradeGrid(section: Obj): Obj {
+  const id = section.id as string;
+  const content = (section.content ?? {}) as Obj;
+  const options = (section.options ?? {}) as Obj;
+  const media = Array.isArray(content.media) ? (content.media as Obj[]) : [];
+
+  const childDefaults: Obj = {};
+  if (options.square !== undefined) childDefaults.square = options.square;
+  if (options.showCaptions !== undefined) childDefaults.showCaption = options.showCaptions; // RENAME plural→singular
+  if (options.border !== undefined) childDefaults.border = options.border;
+  if (options.crop) childDefaults.objectFit = "cover"; // crop:true → 'cover'; else omit (→ contain)
+
+  const out: Obj = {
+    id,
+    type: "container",
+    content: {
+      columns: content.columns,
+      flow: "row",
+      children: media.map((item, i) => mapRefItem(item, id, i)),
+    },
+  };
+  if (Object.keys(childDefaults).length > 0) (out.content as Obj).childDefaults = childDefaults;
+  if (section.layout !== undefined) out.layout = section.layout;
+  return out;
+}
+
+function upgradeSplitContent(section: Obj): Obj {
+  const id = section.id as string;
+  const content = (section.content ?? {}) as Obj;
+  const options = (section.options ?? {}) as Obj;
+
+  const mediaChild: Obj = {
+    id: `${id}__media_0`,
+    type: "media",
+    content: { ref: { type: "image", imageId: content.imageId ?? "" } },
+    options: options.border !== undefined ? { border: options.border } : {},
+  };
+  const proseChild: Obj = {
+    id: `${id}__prose_1`,
+    type: "prose",
+    content: { body: content.body ?? "" },
+  };
+  const children = options.imagePosition === "right" ? [proseChild, mediaChild] : [mediaChild, proseChild];
+
+  const out: Obj = { id, type: "container", content: { columns: 2, flow: "row", children } };
+  if (section.layout !== undefined) out.layout = section.layout;
+  return out;
+}
+
+/** Carry showLabel/stackText onto each icon_list child; omit the options key entirely when neither is set. */
+function dodontChildOptions(options: Obj): Obj | undefined {
+  const out: Obj = {};
+  if (options.showLabel !== undefined) out.showLabel = options.showLabel;
+  if (options.stackText !== undefined) out.stackText = options.stackText;
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/** doItems/dontItems → two tagged icon_list children. dodont forces the glyph, so per-item icon is dropped. */
+function dodontChild(items: Obj[], parentId: string, index: number, tag: "do" | "dont", options: Obj | undefined): Obj {
+  const child: Obj = {
+    id: `${parentId}__icon_list_${index}`,
+    type: "icon_list",
+    content: { items: items.map((it) => ({ label: it.label ?? "", text: it.text ?? "", dodont: tag })) },
+  };
+  if (options !== undefined) child.options = options;
+  return child;
+}
+
+function upgradeDoDont(section: Obj): Obj {
+  const id = section.id as string;
+  const content = (section.content ?? {}) as Obj;
+  const options = (section.options ?? {}) as Obj;
+  const doItems = Array.isArray(content.doItems) ? (content.doItems as Obj[]) : [];
+  const dontItems = Array.isArray(content.dontItems) ? (content.dontItems as Obj[]) : [];
+
+  const childOptions = dodontChildOptions(options);
+  const out: Obj = {
+    id,
+    type: "container",
+    content: {
+      columns: 2,
+      flow: "row",
+      children: [
+        dodontChild(doItems, id, 0, "do", childOptions),
+        dodontChild(dontItems, id, 1, "dont", childOptions),
+      ],
+    },
+  };
+  if (section.layout !== undefined) out.layout = section.layout;
+  return out;
+}