@drawnagency/primitives 0.1.65 → 0.1.67

package/src/components/sections/IconList/IconListSettings.tsx

@@ -1,45 +1,89 @@
 import { useState } from "react";
+import { Check, X } from "lucide-react";
 import { Checkbox } from "../../shared/Checkbox";
 import { FormLabel } from "../../shared/FormLabel";
 import { IconPicker } from "../../primitives/IconPicker";
 import { getIcon } from "../../../lib/icons";
+import { cn } from "../../../lib/cn";
 
 export function IconListSettings({
   icon: initialIcon,
   showLabel: initialShowLabel,
   stackText: initialStackText,
+  dodont: initialDodont,
   onChange,
 }: {
   icon: string | null;
   showLabel: boolean;
   stackText: boolean;
+  dodont?: "do" | "dont";
   onChange: (result: { content: Record<string, unknown>; options: Record<string, unknown> }) => void;
 }) {
   const [icon, setIcon] = useState(initialIcon);
   const [showLabel, setShowLabel] = useState(initialShowLabel);
   const [stackText, setStackText] = useState(initialStackText);
+  const [dodont, setDodont] = useState<"do" | "dont" | undefined>(initialDodont);
   const [pickerOpen, setPickerOpen] = useState(false);
 
-  const emit = (overrides: Partial<{ icon: string | null; showLabel: boolean; stackText: boolean }>) =>
-    onChange({ content: {}, options: { icon, showLabel, stackText, ...overrides } });
+  const emit = (
+    overrides: Partial<{ icon: string | null; showLabel: boolean; stackText: boolean; dodont: "do" | "dont" | undefined }>,
+  ) => onChange({ content: {}, options: { icon, showLabel, stackText, dodont, ...overrides } });
 
-  const showIcons = icon !== null;
   const iconEntry = icon ? getIcon(icon) : null;
+  const dodontActive = dodont === "do" || dodont === "dont";
+
+  const tile = (value: "do" | "dont" | undefined, label: string, aria: string, glyph: React.ReactNode, tint: string) => (
+    <button
+      type="button"
+      aria-label={aria}
+      aria-pressed={dodont === value}
+      className={cn(
+        "cursor-pointer flex flex-col items-center gap-1 rounded border py-2 transition-colors",
+        tint,
+        dodont === value ? "border-primary bg-base-accent" : "border-base-200",
+      )}
+      onClick={() => { setDodont(value); emit({ dodont: value }); }}
+    >
+      {glyph}
+      <span className="text-xs font-medium">{label}</span>
+    </button>
+  );
 
   return (
     <div className="space-y-4">
+      <div>
+        <FormLabel>Do / Don't list</FormLabel>
+        <div className="grid grid-cols-3 gap-2">
+          {tile(
+            undefined,
+            "None",
+            "No do/don't",
+            <span className="flex h-5 w-5 items-center justify-center rounded-sm border border-dashed border-base-contrast-light/40" />,
+            "text-base-contrast-light",
+          )}
+          {tile("do", "Do", "Do list", <Check size={20} />, "text-green-600")}
+          {tile("dont", "Don't", "Don't list", <X size={20} />, "text-red-600")}
+        </div>
+      </div>
+
       <div className="relative">
         <FormLabel htmlFor="icon-picker-btn">Default Icon</FormLabel>
         <div className="flex items-center gap-2">
           <button
             id="icon-picker-btn"
-            className="cursor-pointer flex items-center gap-2 rounded border border-base-200 px-3 py-1.5 text-sm text-base-contrast-light hover:border-primary hover:text-primary"
-            onClick={() => setPickerOpen((prev) => !prev)}
+            disabled={dodontActive}
+            className={cn(
+              "flex items-center gap-2 rounded border border-base-200 px-3 py-1.5 text-sm text-base-contrast-light",
+              dodontActive
+                ? "cursor-not-allowed opacity-50"
+                : "cursor-pointer hover:border-primary hover:text-primary",
+            )}
+            onClick={() => { if (!dodontActive) setPickerOpen((prev) => !prev); }}
           >
             {iconEntry && <iconEntry.icon size={16} />}
             <span>{iconEntry?.label ?? "None"}</span>
           </button>
-          {icon && (
+          {icon && !dodontActive && (
             <button
               className="cursor-pointer text-xs text-base-contrast-light hover:text-base-contrast"
               onClick={() => { setIcon(null); emit({ icon: null }); }}
@@ -48,15 +92,17 @@ export function IconListSettings({
             </button>
           )}
         </div>
-        {pickerOpen && (
+        {dodontActive && (
+          <p className="mt-1 text-xs text-base-contrast-light/70">
+            Whole-list Do/Don't overrides the default icon.
+          </p>
+        )}
+        {pickerOpen && !dodontActive && (
           <div className="absolute top-full left-0 z-50 mt-1">
             <IconPicker
               selected={icon}
               onSelect={(newIcon) => {
-                if (newIcon !== null) {
-                  setIcon(newIcon);
-                  emit({ icon: newIcon });
-                }
+                if (newIcon !== null) { setIcon(newIcon); emit({ icon: newIcon }); }
                 setPickerOpen(false);
               }}
               onClose={() => setPickerOpen(false)}
@@ -64,6 +110,7 @@ export function IconListSettings({
           </div>
         )}
       </div>
+
       <Checkbox
         checked={showLabel}
         onChange={(v) => { setShowLabel(v); emit({ showLabel: v }); }}

package/src/components/sections/IconList/index.tsx

@@ -1,6 +1,8 @@
 import { defineSection } from "../../../lib/registry";
 import { z } from "zod";
-import { List } from "lucide-react";
+import { List, Columns2 } from "lucide-react";
+import type { SectionPreset } from "../../../lib/registry";
+import type { SectionContent } from "../../../schemas/sections";
 import IconList from "./IconList";
 import { IconListSettings } from "./IconListSettings";
 import { pluralize } from "../../../lib/text";
@@ -16,27 +18,68 @@ export type IconListItem = z.infer<typeof IconListItemSchema>;
 const schema = z.object({
   type: z.literal("icon_list"),
   content: z.object({
-    items: z.array(IconListItemSchema),
+    items: z
+      .array(IconListItemSchema)
+      .describe(
+        "The list entries. Each item has a label, descriptive text, an optional icon, and an optional do/don't marker.",
+      ),
   }),
-  options: z.object({
-    icon: z.string().nullable().optional(),
-    showLabel: z.boolean().optional(),
-    stackText: z.boolean().optional(),
-  }).optional(),
+  options: z
+    .object({
+      icon: z
+        .string()
+        .nullable()
+        .describe("Default icon name applied to items that don't specify their own; null for no icon.")
+        .optional(),
+      showLabel: z.boolean().describe("When true, render each item's label.").optional(),
+      stackText: z
+        .boolean()
+        .describe("When true, stack the label and text vertically instead of inline.")
+        .optional(),
+      dodont: z
+        .enum(["do", "dont"])
+        .describe("Whole-list do/don't mode: render every item with a green check (do) or red x (don't).")
+        .optional(),
+    })
+    .optional(),
 });
 
+// One-click "Do / Don't list": a 2-column container holding a green-check "Do"
+// icon_list and a red-x "Don't" icon_list, using the whole-list options.dodont
+// default. Same shape the legacy do_dont migration produces. Lives here (brand-guide
+// layer); it reaches the core Add-menu only via SectionDefinition.presets.
+const doDontListPreset: SectionPreset = {
+  id: "do_dont_list",
+  label: "Do / Don't list",
+  icon: <Columns2 size={18} />,
+  build: (newId): SectionContent => ({
+    type: "container",
+    content: {
+      columns: 2,
+      flow: "row",
+      children: [
+        { id: newId(), type: "icon_list", content: { items: [{ label: "", text: "" }] }, options: { dodont: "do" } },
+        { id: newId(), type: "icon_list", content: { items: [{ label: "", text: "" }] }, options: { dodont: "dont" } },
+      ],
+    },
+  }),
+};
+
 export default defineSection({
   type: "icon_list",
   category: "brand-guide",
   label: "Icon List",
   icon: <List size={18} />,
   schema,
+  authoringNote:
+    "A list of labeled items, optionally with per-item icons and do/don't markers. Use for feature lists, guidelines, or do/don't guidance.",
   component: ({ content, options, onChange }) => (
     <IconList
       items={content.content.items}
       icon={options?.icon as string | null}
       showLabel={options?.showLabel as boolean}
       stackText={options?.stackText as boolean}
+      dodont={options?.dodont as "do" | "dont" | undefined}
       onChange={onChange ? (c) => onChange(c as typeof content) : undefined}
     />
   ),
@@ -46,4 +89,5 @@ export default defineSection({
   }),
   getLabel: (content) => pluralize(content.content.items.length, "icon"),
   settingsForm: IconListSettings,
+  presets: [doDontListPreset],
 });

package/src/components/sections/LinkHeading/index.tsx

@@ -9,4 +9,6 @@ export default defineHeadingSection({
   tag: "h2",
   placeholder: "Section heading",
   defaultHeading: "New Section",
+  authoringNote:
+    "A top-level section heading (renders an <h2>, reported to navigation as h1). Use it to begin a major named section of the guide; its text becomes a navigation entry.",
 });

package/src/components/sections/Media/MediaBlock.tsx

@@ -33,12 +33,18 @@ export function MediaBlock({ refValue, options, link, isEditMode, onRefChange }:
   // placeholder. In edit mode these are absent and ResolvedMedia falls back to the
   // live manifest via context. (Mirrors a3e8913, which did this for MediaGrid/SplitContent.)
   const baked = refValue as Record<string, unknown>;
+  const bakedWidth = typeof baked.width === "number" ? baked.width : undefined;
+  const bakedHeight = typeof baked.height === "number" ? baked.height : undefined;
+  const aspectRatio =
+    bakedWidth && bakedHeight && !options.square ? `${bakedWidth} / ${bakedHeight}` : undefined;
   const resolved = (
     <ResolvedMedia
       imageId={refValue.imageId || undefined}
       src={baked.src as string | undefined}
       srcset={baked.srcset as string | undefined}
       alt={baked.alt as string | undefined}
+      width={bakedWidth}
+      height={bakedHeight}
       className="h-full w-full"
       imgClassName={fitClass}
       invertFrom={refValue.invertFrom}
@@ -75,6 +81,7 @@ export function MediaBlock({ refValue, options, link, isEditMode, onRefChange }:
           options.square && "aspect-square",
           onImageClick && "cursor-pointer",
         )}
+        style={aspectRatio ? { aspectRatio } : undefined}
         onClick={onImageClick}
         onPointerDown={onImageClick ? (e) => e.stopPropagation() : undefined}
       >

package/src/components/sections/Media/index.tsx

@@ -8,15 +8,22 @@ import { MediaBlock } from "./MediaBlock";
 const schema = z.object({
   type: z.literal("media"),
   content: z.object({
-    ref: SingleMediaReferenceSchema,
-    link: LinkValueSchema.optional(),
+    ref: SingleMediaReferenceSchema.describe(
+      "The image or video asset to display (a media reference by id). Required.",
+    ),
+    link: LinkValueSchema.describe(
+      "Optional link wrapping the media — an internal page or a safe external URL.",
+    ).optional(),
   }),
   options: z
     .object({
-      square: z.boolean().optional(),
-      showCaption: z.boolean().optional(),
-      border: z.boolean().optional(),
-      objectFit: z.enum(["cover", "contain"]).optional(),
+      square: z.boolean().describe("When true, crop the media to a 1:1 square aspect ratio.").optional(),
+      showCaption: z.boolean().describe("When true, render the asset's caption beneath it.").optional(),
+      border: z.boolean().describe("When true, draw a border around the media.").optional(),
+      objectFit: z
+        .enum(["cover", "contain"])
+        .describe("How the image fills its box: 'contain' (fit whole image) or 'cover' (fill and crop).")
+        .optional(),
     })
     .default({}),
 });
@@ -26,6 +33,8 @@ export default defineSection({
   label: "Media",
   icon: <ImageIcon size={18} />,
   schema,
+  authoringNote:
+    "A single image or video with optional caption and link. Use to show one asset; for several assets side by side, place multiple Media blocks inside a Container.",
   component: ({ content, options, onChange }) => (
     <MediaBlock
       refValue={content.content.ref}

package/src/components/sections/Prose/index.tsx

@@ -6,7 +6,13 @@ import { stripHtmlToPlainText, truncate } from "../../../lib/text";
 
 const schema = z.object({
   type: z.literal("prose"),
-  content: z.object({ body: z.string() }),
+  content: z.object({
+    body: z
+      .string()
+      .describe(
+        "Rich-text HTML for the paragraph block. Author with the editor; stored as sanitized HTML.",
+      ),
+  }),
 });
 
 export default defineSection({
@@ -14,6 +20,8 @@ export default defineSection({
   label: "Prose",
   icon: <AlignLeft size={18} />,
   schema,
+  authoringNote:
+    "A block of rich-text body copy (paragraphs, lists, inline emphasis, links). Use for any explanatory prose; author with the editor, not raw HTML.",
   richTextFields: ["body"],
   component: ({ content, onChange }) => (
     <Prose body={content.content.body} onChange={onChange ? (c) => onChange(c as typeof content) : undefined} />

package/src/components/sections/Spacer/index.tsx

@@ -13,6 +13,8 @@ export default defineSection({
   label: "Spacer",
   icon: <SquareDashed size={18} />,
   schema,
+  authoringNote:
+    "Vertical whitespace between sections. Use sparingly to add breathing room where default section spacing is insufficient.",
   component: () => <Spacer />,
   defaults: () => ({ type: "spacer" as const, content: {} }),
 });

package/src/components/sections/SubHeading/index.tsx

@@ -10,4 +10,6 @@ export default defineHeadingSection({
   placeholder: "Sub heading",
   defaultHeading: "New Sub Heading",
   navExclusion: true,
+  authoringNote:
+    "A second-level heading (renders <h3>, nav level h2). Use under a Link Heading to divide a section; toggle Exclude from navigation to keep it out of the nav tree.",
 });

package/src/components/sections/SubSubHeading/index.tsx

@@ -10,4 +10,6 @@ export default defineHeadingSection({
   placeholder: "Sub sub heading",
   defaultHeading: "New Sub Sub Heading",
   navExclusion: true,
+  authoringNote:
+    "A third-level heading (renders <h4>, nav level h3). Use for the finest-grained labeled subsection; toggle Exclude from navigation to omit it from the nav tree.",
 });

package/src/components/shared/PasswordInput.tsx

@@ -43,15 +43,15 @@ export function PasswordInput({
           className={cn(
             "w-full rounded border border-base-200 bg-base px-3 py-2 text-sm text-base-contrast",
             "focus:border-base-contrast focus:outline-none focus:ring-1 focus:ring-base-contrast",
-            showToggle && "pr-9",
+            showToggle && "pr-10",
             disabled && "cursor-not-allowed opacity-50",
           )}
         />
         {showToggle && (
           <IconButton
-            icon={revealed ? <EyeOff size={16} /> : <Eye size={16} />}
+            icon={revealed ? <EyeOff size={20} /> : <Eye size={20} />}
             label={revealed ? "Hide password" : "Show password"}
-            size="sm"
+            size="md"
             aria-pressed={revealed}
             disabled={disabled}
             onClick={() => setRevealed((v) => !v)}

package/src/components/shell/EditorLoading.tsx

@@ -0,0 +1,37 @@
+import { useEffect, useState } from "react";
+import { Loader2 } from "lucide-react";
+
+interface EditorLoadingProps {
+  /** Delay before the spinner appears, to avoid a flash on instant cache hits. */
+  delayMs?: number;
+}
+
+/**
+ * Full-screen loading state shown while EditorShell hydrates and loads content.
+ * Keeps the existing aria-busy contract on the wrapper at all times; the visible
+ * spinner is delayed so a fast Dexie cache hit doesn't flash it. SSR-safe: the
+ * initial render shows the wrapper with no spinner, matching the server output.
+ */
+export function EditorLoading({ delayMs = 200 }: EditorLoadingProps) {
+  const [showSpinner, setShowSpinner] = useState(false);
+
+  useEffect(() => {
+    const timer = setTimeout(() => setShowSpinner(true), delayMs);
+    return () => clearTimeout(timer);
+  }, [delayMs]);
+
+  return (
+    <div
+      className="flex min-h-screen items-center justify-center"
+      aria-busy="true"
+      aria-label="Loading content"
+    >
+      {showSpinner && (
+        <Loader2
+          className="size-8 animate-spin text-primary"
+          data-testid="editor-loading-spinner"
+        />
+      )}
+    </div>
+  );
+}

package/src/components/shell/EditorShell.tsx

@@ -27,6 +27,7 @@ import { SectionTypePicker } from "./SectionTypePicker";
 import { ensureSectionsRegistered } from "../sections/register";
 import { getSection, getAllSections } from "../../lib/registry";
 import { childInsertableTypes, insertChildAt } from "../../lib/container-ops";
+import { buildInsertMenuOptions, resolveInsertedContent } from "../../lib/insert-menu";
 
 ensureSectionsRegistered();
 import { BugReportFAB } from "./BugReportFAB";
@@ -75,6 +76,7 @@ import { ImageIcon, ListOrderedIcon, FilesIcon, X } from "lucide-react";
 import { ErrorBoundary } from "../shared/ErrorBoundary";
 import { HistoryToolbar } from "./HistoryToolbar";
 import { RestoreModal } from "./RestoreModal";
+import { EditorLoading } from "./EditorLoading";
 import ViewRenderer from "../sections/ViewRenderer";
 
 export { useMediaLibrary } from "./MediaLibraryContext";
@@ -590,13 +592,16 @@ export default function EditorShell({
   );
 
   const onAddSection = useCallback(
-    (insertIndex: number, type: string) => {
-      const definition = getSection(type);
-      if (!definition || !resolvedActivePage) return;
-      const id = typeof crypto !== "undefined" && typeof crypto.randomUUID === "function"
-        ? crypto.randomUUID() : `_id_${Date.now()}_${Math.random().toString(36).slice(2)}`;
-      const content = definition.defaults() as object;
-      const meta = { type, status: "draft" as const, access: [] as string[] };
+    (insertIndex: number, selection: string) => {
+      if (!resolvedActivePage) return;
+      const newId = () =>
+        typeof crypto !== "undefined" && typeof crypto.randomUUID === "function"
+          ? crypto.randomUUID()
+          : `_id_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+      const content = resolveInsertedContent(selection, getAllSections(), newId);
+      if (!content) return;
+      const id = newId();
+      const meta = { type: content.type, status: "draft" as const, access: [] as string[] };
       const newSection: LoadedSection = { section: { id, ...content } as LoadedSection["section"], meta };
 
       setSections((prev) => [...prev, newSection]);
@@ -808,7 +813,7 @@ export default function EditorShell({
   // --- Render ---
 
   if (shellState.phase === "loading-content") {
-    return <div className="min-h-screen" aria-busy="true" aria-label="Loading content" />;
+    return <EditorLoading />;
   }
 
   if (shellState.phase === "error") {
@@ -1188,7 +1193,7 @@ function EditorContent({
   dirtySectionIds: Set<string>;
   isPublishing: boolean;
   onSectionChange: (sectionId: string, content: SectionContent) => void;
-  onAddSection: (insertIndex: number, type: string) => void;
+  onAddSection: (insertIndex: number, selection: string) => void;
   onDeleteSection: (sectionId: string) => void;
   onReorderSections: (fromIndex: number, toIndex: number) => void;
   onBlockMove: (move: BlockMove) => void;
@@ -1204,17 +1209,7 @@ function EditorContent({
   const [pendingInsertIndex, setPendingInsertIndex] = useState<number | null>(null);
   const dismissPendingInsert = useCallback(() => setPendingInsertIndex(null), []);
 
-  const typeOptions = useMemo(
-    () =>
-      getAllSections()
-        .filter((def) => def.type !== "spacer")
-        .map((def) => ({
-          type: def.type,
-          label: def.label,
-          icon: def.icon,
-        })),
-    [],
-  );
+  const typeOptions = useMemo(() => buildInsertMenuOptions(getAllSections()), []);
 
   const editingEnabled = isEditMode && !isPublishing;
 

package/src/components/shell/SiteSettingsDisplay.tsx

@@ -48,8 +48,15 @@ export function SiteSettingsDisplay({ siteConfig, onChange }: Props) {
   }
 
   function handleColorChange(color: string) {
-    const contrast = deriveContrast(color);
-    onChange({ ...siteConfig, primaryColor: color, primaryContrast: contrast });
+    update({ primaryColor: color });
+  }
+
+  function handleContrastChange(color: string) {
+    update({ primaryContrast: color });
+  }
+
+  function resetContrastToAuto() {
+    update({ primaryContrast: deriveContrast(siteConfig.primaryColor) });
   }
 
   function handleFontChange(field: "headingFont" | "bodyFont", family: string) {
@@ -79,6 +86,25 @@ export function SiteSettingsDisplay({ siteConfig, onChange }: Props) {
         </div>
       </div>
 
+      <div>
+        <FormLabel>Accent (button &amp; highlight text)</FormLabel>
+        <div className="flex items-center gap-3">
+          <ColorPicker
+            value={siteConfig.primaryContrast}
+            onChange={handleContrastChange}
+            label="Accent color"
+          />
+          <span className="text-sm text-base-contrast-light">{siteConfig.primaryContrast}</span>
+          <Button type="button" variant="ghost" size="sm" onClick={resetContrastToAuto}>
+            Reset to auto
+          </Button>
+        </div>
+        <p className="mt-1 text-xs text-base-contrast/70">
+          Shown as text on primary-colored buttons and as the text-selection color. "Reset to auto" derives a
+          legible light or dark value from your primary brand color.
+        </p>
+      </div>
+
       <div>
         <FormLabel>Favicon</FormLabel>
         <div className="flex items-center gap-3">

package/src/hooks/useResolvedMedia.ts

@@ -8,6 +8,8 @@ export interface ResolvedMediaResult {
   poster: string | undefined;
   alt: string;
   kind: "image" | "animated" | "video";
+  width?: number;
+  height?: number;
 }
 
 export function useResolvedMedia(imageId: string | undefined): ResolvedMediaResult {
@@ -26,10 +28,12 @@ export function useResolvedMedia(imageId: string | undefined): ResolvedMediaResu
     const item = manifestItem ?? pendingItem;
     const alt = item?.alt ?? "";
     const kind = item?.kind ?? "image";
+    const width = item?.width;
+    const height = item?.height;
 
     const localUrl = pendingLocalUrls[imageId];
     if (localUrl) {
-      return { src: localUrl, srcset: undefined, poster: undefined, alt, kind };
+      return { src: localUrl, srcset: undefined, poster: undefined, alt, kind, width, height };
     }
 
     if (manifestItem) {
@@ -42,13 +46,15 @@ export function useResolvedMedia(imageId: string | undefined): ResolvedMediaResu
           poster: undefined,
           alt,
           kind,
+          width: resolved.width,
+          height: resolved.height,
         };
       }
       if (resolved && resolved.tag === "video") {
-        return { src: resolved.src, srcset: undefined, poster: resolved.poster, alt, kind };
+        return { src: resolved.src, srcset: undefined, poster: resolved.poster, alt, kind, width: resolved.width, height: resolved.height };
       }
     }
 
-    return { src: undefined, srcset: undefined, poster: undefined, alt, kind };
+    return { src: undefined, srcset: undefined, poster: undefined, alt, kind, width, height };
   }, [imageId, ctx]);
 }

package/src/lib/insert-menu.ts

@@ -0,0 +1,42 @@
+import type { ReactNode } from "react";
+import type { SectionDefinition } from "./registry";
+import type { SectionContent } from "../schemas/sections";
+
+/** Namespacing prefix for preset selections in the Add-section menu. */
+export const PRESET_PREFIX = "__preset:";
+
+/** One Add-section menu entry: a section `type`, or `__preset:<presetId>`. */
+export interface InsertMenuOption {
+  type: string;
+  label: string;
+  icon?: ReactNode;
+}
+
+/** Every non-spacer section type, followed by presets contributed by registered
+ *  sections. Presets appear only when their owning section is registered, so a
+ *  core-only build (no brand-guide sections) shows no brand-guide presets. */
+export function buildInsertMenuOptions(sections: SectionDefinition[]): InsertMenuOption[] {
+  const typeOptions = sections
+    .filter((def) => def.type !== "spacer")
+    .map((def) => ({ type: def.type, label: def.label, icon: def.icon }));
+  const presetOptions = sections
+    .flatMap((def) => def.presets ?? [])
+    .map((p) => ({ type: `${PRESET_PREFIX}${p.id}`, label: p.label, icon: p.icon }));
+  return [...typeOptions, ...presetOptions];
+}
+
+/** Resolve an Add-menu selection to ready-to-insert content. `newId` mints ids for
+ *  any nested children a preset creates. Returns null for an unknown type/preset. */
+export function resolveInsertedContent(
+  selection: string,
+  sections: SectionDefinition[],
+  newId: () => string,
+): SectionContent | null {
+  if (selection.startsWith(PRESET_PREFIX)) {
+    const id = selection.slice(PRESET_PREFIX.length);
+    const preset = sections.flatMap((def) => def.presets ?? []).find((p) => p.id === id);
+    return preset ? preset.build(newId) : null;
+  }
+  const def = sections.find((d) => d.type === selection);
+  return def ? (def.defaults() as SectionContent) : null;
+}

package/src/lib/registry.ts

@@ -2,6 +2,7 @@ import type { ZodType, z } from "zod";
 import type { ComponentType, ReactNode } from "react";
 import type { Audience } from "../schemas/auth";
 import type { LinkValue } from "../schemas/link";
+import type { SectionContent } from "../schemas/sections";
 
 // --- Settings field types ---
 
@@ -106,6 +107,19 @@ export interface WrapperProps {
 
 // --- Section definition ---
 
+/**
+ * A ready-to-insert composite (e.g. a container of preconfigured child sections),
+ * surfaced in the Add-section menu. Contributed by the section definition that owns
+ * the composition, so it rides the section registry and disappears in a core-only
+ * build that never registers that section. `newId` mints unique ids for nested children.
+ */
+export interface SectionPreset {
+  id: string;
+  label: string;
+  icon?: ReactNode;
+  build(newId: () => string): SectionContent;
+}
+
 export interface SectionDefinition<T = unknown> {
   type: string;
   /** Grouping label. `"brand-guide"` marks opinionated sections separable from the
@@ -136,6 +150,14 @@ export interface SectionDefinition<T = unknown> {
    * into a trailing 'Other' tab.
    */
   settingsTabs?: { label: string; fields: string[] }[];
+  /** Composite blueprints for the Add-section menu (see SectionPreset). */
+  presets?: SectionPreset[];
+  /**
+   * Human/agent-facing prose describing when to use this section type and how to
+   * author it well. Surfaced by the get_section_schema tool as the JSON Schema
+   * top-level `description`. Presentation/metadata only — not validated.
+   */
+  authoringNote?: string;
 }
 
 // --- defineSection ---
@@ -162,6 +184,8 @@ type DefineSectionInput<S extends ZodType> = {
    * into a trailing 'Other' tab.
    */
   settingsTabs?: { label: string; fields: string[] }[];
+  presets?: SectionPreset[];
+  authoringNote?: string;
 };
 
 export function defineSection<S extends ZodType>(