@drawnagency/primitives 0.1.55 → 0.1.57

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

@@ -40,6 +40,12 @@ interface ContentCacheRow {
   index: SiteIndex;
   siteConfig: Record<string, unknown>;
   updatedAt: string;
+  // Draft-vs-published diff state, cached alongside the content so a cache hit
+  // (same sha) restores the editor's "changed since published" indicators
+  // without re-deriving them from GitHub. Optional for backward compatibility.
+  savedBranchSha?: string | null;
+  changedSectionIds?: string[];
+  mainIndex?: SiteIndex | null;
 }
 
 interface MediaManifestRow {
@@ -136,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();
+    });
   }
 }
 
@@ -389,6 +417,7 @@ export async function cacheContent(
   sections: LoadedSection[],
   index: SiteIndex,
   siteConfig: Record<string, unknown>,
+  diff?: { savedBranchSha: string | null; changedSectionIds: string[]; mainIndex: SiteIndex | null },
 ): Promise<void> {
   const now = new Date().toISOString();
   await getDb().contentCache.put({
@@ -398,6 +427,9 @@ export async function cacheContent(
     index,
     siteConfig,
     updatedAt: now,
+    savedBranchSha: diff?.savedBranchSha ?? null,
+    changedSectionIds: diff?.changedSectionIds ?? [],
+    mainIndex: diff?.mainIndex ?? null,
   });
 }
 
@@ -406,6 +438,9 @@ export async function getCachedContent(): Promise<{
   sections: LoadedSection[];
   index: SiteIndex;
   siteConfig: Record<string, unknown>;
+  savedBranchSha: string | null;
+  changedSectionIds: string[];
+  mainIndex: SiteIndex | null;
 } | null> {
   const row = await getDb().contentCache.get("current");
   if (!row) return null;
@@ -414,9 +449,21 @@ export async function getCachedContent(): Promise<{
     sections: row.sections,
     index: row.index,
     siteConfig: row.siteConfig,
+    savedBranchSha: row.savedBranchSha ?? null,
+    changedSectionIds: row.changedSectionIds ?? [],
+    // No stored mainIndex (e.g. legacy or post-publish cache) means "no draft",
+    // so the published index equals the current index.
+    mainIndex: row.mainIndex ?? row.index,
   };
 }
 
+/** Invalidate only the cached content snapshot (e.g. after a publish removes the
+ * draft), forcing the next editor load to refetch rather than serve stale diff
+ * state. Narrower than discardSavedChanges, which also clears index/meta/config. */
+export async function clearContentCache(): Promise<void> {
+  await getDb().contentCache.clear();
+}
+
 export async function persistMediaManifest(manifest: MediaManifest): Promise<void> {
   const now = new Date().toISOString();
   await getDb().mediaManifest.put({ key: "current", manifest, updatedAt: now });

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;
+}

package/src/lib/registry.ts

@@ -33,6 +33,11 @@ export type SettingsFieldDef =
       default: string;
       target?: "content" | "options";
       coerce?: "number";
+      /** When set, an empty-string ("") selection is normalized to `undefined`
+       * before the content/options split, so an optional-enum field clears cleanly
+       * (e.g. Media `dodont`, whose enum is strictly ["do","dont"]). Opt-in so other
+       * selects keep their "" value. */
+      emptyIsUndefined?: boolean;
       options: { label: string; value: string }[];
     }
   | {
@@ -79,6 +84,8 @@ export interface WrapperProps {
   dirty?: boolean;
   index: number;
   isLast: boolean;
+  containerId: string;
+  isContainerBlock: boolean;
   definition: SectionDefinition;
   options?: Record<string, unknown>;
   audiences: Audience[];
@@ -90,6 +97,7 @@ export interface WrapperProps {
   onRequestInsert?: (index: number) => void;
   onDelete?: () => void;
   onMoveSection?: () => void;
+  onAddChild?: () => void;
   mainStatus?: string | null;
   contentDiffersFromMain?: boolean;
   isLocalOnly?: boolean;
@@ -105,13 +113,25 @@ export interface SectionDefinition<T = unknown> {
   schema: ZodType<T>;
   component: ComponentType<SectionProps<T>>;
   defaults: () => T;
-  wrapper?: ComponentType<WrapperProps>;
   settings?: SettingsSchema;
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   settingsForm?: ComponentType<any>;
   getLabel?(content: T): string;
   getThumbnails?(content: T): Thumbnail[];
   navRole?: "h1" | "h2" | "h3";
+  /** content-relative field paths that hold HTML rich text (for the sanitizer). */
+  richTextFields?: readonly string[];
+  /**
+   * Option keys (under this type's `options`) that a parent container may set as a
+   * default for all children via `content.childDefaults`. v1: typed primitives only.
+   */
+  inheritableSettings?: readonly string[];
+  /**
+   * Optional grouping of `settings` fields into labeled tabs for the settings modal;
+   * presentation-only — does not change content/options routing; omitted fields fall
+   * into a trailing 'Other' tab.
+   */
+  settingsTabs?: { label: string; fields: string[] }[];
 }
 
 // --- defineSection ---
@@ -123,13 +143,20 @@ type DefineSectionInput<S extends ZodType> = {
   schema: S;
   component: ComponentType<SectionProps<z.infer<S>>>;
   defaults: () => z.infer<S>;
-  wrapper?: ComponentType<WrapperProps>;
   settings?: SettingsSchema;
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   settingsForm?: ComponentType<any>;
   getLabel?(content: z.infer<S>): string;
   getThumbnails?(content: z.infer<S>): Thumbnail[];
   navRole?: "h1" | "h2" | "h3";
+  richTextFields?: readonly string[];
+  inheritableSettings?: readonly string[];
+  /**
+   * Optional grouping of `settings` fields into labeled tabs for the settings modal;
+   * presentation-only — does not change content/options routing; omitted fields fall
+   * into a trailing 'Other' tab.
+   */
+  settingsTabs?: { label: string; fields: string[] }[];
 };
 
 export function defineSection<S extends ZodType>(
@@ -148,6 +175,8 @@ export interface SectionRegistry {
   getSchema(type: string): ZodType | undefined;
   getAllSections(): SectionDefinition[];
   getAllSchemas(): ZodType[];
+  registerRichText(type: string, fields: readonly string[]): void;
+  getRichTextFields(type: string): readonly string[];
   clearRegistry(): void;
 }
 
@@ -155,14 +184,22 @@ export function createRegistry(): SectionRegistry {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const sections = new Map<string, SectionDefinition<any>>();
   const schemas = new Map<string, ZodType>();
+  const richText = new Map<string, readonly string[]>();
 
   return {
     registerSection(def) {
       sections.set(def.type, def);
+      if (def.richTextFields) richText.set(def.type, def.richTextFields);
     },
     registerSchema(type, schema) {
       schemas.set(type, schema);
     },
+    registerRichText(type, fields) {
+      richText.set(type, fields);
+    },
+    getRichTextFields(type) {
+      return richText.get(type) ?? [];
+    },
     getSection(type) {
       return sections.get(type);
     },
@@ -182,6 +219,7 @@ export function createRegistry(): SectionRegistry {
     clearRegistry() {
       sections.clear();
       schemas.clear();
+      richText.clear();
     },
   };
 }
@@ -204,6 +242,14 @@ export function registerSchema(type: string, schema: ZodType): void {
   defaultRegistry.registerSchema(type, schema);
 }
 
+export function registerRichText(type: string, fields: readonly string[]): void {
+  defaultRegistry.registerRichText(type, fields);
+}
+
+export function getRichTextFields(type: string): readonly string[] {
+  return defaultRegistry.getRichTextFields(type);
+}
+
 export function getSection(type: string): SectionDefinition | undefined {
   return defaultRegistry.getSection(type);
 }

package/src/lib/sanitize.ts

@@ -9,6 +9,14 @@ if (typeof window !== "undefined") {
   });
 }
 
+// Memoize sanitized output per input string. In the editor, every keystroke
+// re-renders all sections, re-running DOMPurify (CPU-heavy HTML parsing) on
+// every inactive rich-text block whose HTML hasn't changed. Caching by input
+// value makes those repeats free. Bounded with FIFO eviction so it can't grow
+// without limit across a long editing session.
+const sanitizeCache = new Map<string, string>();
+const SANITIZE_CACHE_LIMIT = 500;
+
 /**
  * Synchronous sanitizer — returns sanitized HTML if DOMPurify has loaded,
  * otherwise returns raw HTML. Call `ensureSanitizer()` during component mount
@@ -16,7 +24,20 @@ if (typeof window !== "undefined") {
  */
 export function sanitizeHtml(html: string): string {
   if (!html) return "";
-  return purifier ? purifier(html) : html;
+  // Don't cache the pre-DOMPurify passthrough — once the purifier loads, the
+  // same input must produce sanitized output.
+  if (!purifier) return html;
+
+  const cached = sanitizeCache.get(html);
+  if (cached !== undefined) return cached;
+
+  const clean = purifier(html);
+  if (sanitizeCache.size >= SANITIZE_CACHE_LIMIT) {
+    const oldest = sanitizeCache.keys().next().value;
+    if (oldest !== undefined) sanitizeCache.delete(oldest);
+  }
+  sanitizeCache.set(html, clean);
+  return clean;
 }
 
 /**

package/src/schemas/block.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+
+/**
+ * A block's participation in its parent container's layout — distinct from its
+ * content. Optional, and absent at the page root (the root is an implicit single
+ * column). Intentionally NOT strict so future keys (rowSpan, alignSelf) are
+ * forward-compatible.
+ */
+export const LayoutEnvelopeSchema = z.object({
+  colSpan: z.number().int().min(1).optional(),
+});
+
+export type LayoutEnvelope = z.infer<typeof LayoutEnvelopeSchema>;
+
+/** v1 nesting cap: a top-level container (depth 2) may hold leaves but not containers. */
+export const MAX_BLOCK_DEPTH = 2;
+
+/** Content-agnostic: any block whose `content.children` is an array is a container. */
+export function getBlockChildren(block: unknown): unknown[] {
+  if (typeof block !== "object" || block === null) return [];
+  const content = (block as { content?: unknown }).content;
+  if (typeof content !== "object" || content === null) return [];
+  const children = (content as { children?: unknown }).children;
+  return Array.isArray(children) ? children : [];
+}
+
+/** Depth of a block tree: a leaf is 1; a container is 1 + max(child depths). */
+export function blockDepth(block: unknown): number {
+  const children = getBlockChildren(block);
+  if (children.length === 0) return 1;
+  return 1 + Math.max(...children.map(blockDepth));
+}
+
+/** Throws if the block tree is deeper than `max`. */
+export function assertMaxDepth(block: unknown, max: number = MAX_BLOCK_DEPTH): void {
+  const depth = blockDepth(block);
+  if (depth > max) {
+    throw new Error(`Block tree depth ${depth} exceeds MAX_BLOCK_DEPTH (${max})`);
+  }
+}

package/src/schemas/link.ts

@@ -2,8 +2,26 @@ import { z } from "zod";
 
 export const LinkTargetSchema = z.enum(["_self", "_blank"]);
 
+/**
+ * Block dangerous href schemes (javascript:, data:, vbscript:) and protocol-
+ * relative URLs at the schema boundary. Allows empty (unset), relative paths /
+ * fragments / queries, and http(s)/mailto absolute URLs. Links are not walked by
+ * the recursive sanitizer, so this is the only XSS guard for stored link hrefs.
+ */
+export function isSafeHref(href: string): boolean {
+  // Browsers strip leading ASCII whitespace and embedded \t \r \n before
+  // interpreting the scheme, so normalize the same way before checking.
+  const normalized = href.replace(/[\t\r\n]/g, "").trimStart();
+  if (normalized === "") return true;
+  if (normalized.startsWith("//")) return false; // protocol-relative
+  const scheme = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(normalized);
+  if (!scheme) return true; // no scheme → relative path / fragment / query
+  const s = scheme[1].toLowerCase();
+  return s === "http" || s === "https" || s === "mailto";
+}
+
 export const LinkValueSchema = z.discriminatedUnion("kind", [
-  z.object({ kind: z.literal("external"), href: z.string(), target: LinkTargetSchema }),
+  z.object({ kind: z.literal("external"), href: z.string().refine(isSafeHref, "Unsafe href scheme"), target: LinkTargetSchema }),
   z.object({
     kind: z.literal("internal"),
     pageId: z.string(),