@openpresentation/opf-editor 0.24.2 → 0.25.0

package/dist/layout-palette.js

@@ -0,0 +1,77 @@
+// The tool palette of the layout editor (RR-99): a vertical icon toolbar, as in Figma. It sets the model's active tool; the canvas acts on it.
+import { createLayoutModel } from "./layout-model.js";
+import { createDom, handleGlobalShortcut } from "./layout-editor-ui.js";
+
+/** The tools, in palette order. `key` is the shortcut letter. */
+export const LAYOUT_TOOL_DEFS = Object.freeze([
+  { id: "select", label: "Select", key: "V", icon: "MousePointer2", help: "Click a region to select it. Click again inside a split to select what is inside." },
+  { id: "split-row", label: "Split into a row", key: "R", icon: "Columns2", help: "Click a region to split it into two side by side." },
+  { id: "split-column", label: "Split into a column", key: "C", icon: "Rows2", help: "Click a region to split it into two, one above the other." },
+  { id: "insert", label: "Insert region", key: "I", icon: "BetweenHorizontalStart", help: "Click between regions, or at the edge of a split, to insert a region there." },
+  { id: "heading", label: "Heading regions", key: "T", icon: "Heading", help: "Add or remove the title and subtitle regions." },
+  { id: "hand", label: "Hand", key: "H", icon: "Hand", help: "Drag to pan the slide when it is zoomed. Hold Space for the same." },
+]);
+export const LAYOUT_PREVIEW_DEF = Object.freeze({ id: "preview", label: "Preview", key: "P", icon: "Eye", help: "Show sample content in each region." });
+
+/**
+ * Mount the tool palette in `container`. Options: `model` (shared state; one is created when omitted, with `record`, `density` and the
+ * other model options), `orientation` ("vertical" or "horizontal"), `label` (accessible name of the toolbar). Returns `{ element, model,
+ * refresh, destroy }`.
+ */
+export function createLayoutToolPalette(container, options = {}) {
+  if (!container?.ownerDocument) throw new TypeError("A DOM container is required.");
+  const dom = createDom(container.ownerDocument);
+  const ownModel = !options.model;
+  const model = options.model ?? createLayoutModel(options);
+  const orientation = options.orientation === "horizontal" ? "horizontal" : "vertical";
+  const root = dom.el("div", "opf-lx-palette opf-ui", { role: "toolbar", "aria-orientation": orientation, "aria-label": options.label ?? "Layout tools", "data-density": model.density, "data-orientation": orientation });
+  const buttons = new Map();
+  const make = (def, toggle) => {
+    const node = dom.button("opf-lx-tool", { label: def.label, iconName: def.icon, size: 18, pressed: false, title: `${def.label} (${def.key})`, attributes: { "data-tool": def.id, "aria-keyshortcuts": def.key } });
+    node.addEventListener("click", () => { if (toggle) model.setPreview(!model.preview); else model.setTool(model.tool === def.id && def.id !== "select" ? "select" : def.id); });
+    buttons.set(def.id, node);
+    return node;
+  };
+  for (const def of LAYOUT_TOOL_DEFS) root.append(make(def, false));
+  root.append(dom.el("span", "opf-lx-tool-gap", { role: "separator", "aria-orientation": orientation === "vertical" ? "horizontal" : "vertical" }));
+  root.append(make(LAYOUT_PREVIEW_DEF, true));
+  container.append(root);
+
+  let rover = "select";
+  function paint() {
+    root.dataset.density = model.density;
+    for (const [id, node] of buttons) {
+      const on = id === "preview" ? model.preview : model.tool === id;
+      node.setAttribute("aria-pressed", String(on));
+      node.classList.toggle("is-active", on);
+      node.tabIndex = id === rover ? 0 : -1;
+      node.disabled = model.readOnly && id !== "hand" && id !== "preview" && id !== "select";
+    }
+  }
+  const unsubscribe = model.subscribe((event) => {
+    if (event.type === "tool" || event.type === "view" || event.type === "load") { if (event.type === "tool" && buttons.has(model.tool)) rover = model.tool; paint(); }
+  });
+  root.addEventListener("focusin", (event) => { const id = event.target.dataset?.tool; if (id && buttons.has(id)) { rover = id; for (const [key, node] of buttons) node.tabIndex = key === rover ? 0 : -1; } });
+  root.addEventListener("keydown", (event) => {
+    if (handleGlobalShortcut(event, model)) return;
+    const order = [...buttons.keys()].filter((id) => !buttons.get(id).disabled);
+    const at = order.indexOf(event.target.dataset?.tool);
+    // Both axes move along the toolbar: it is a column on a wide editor and a row on a narrow one.
+    let to = -1;
+    if (event.key === "ArrowDown" || event.key === "ArrowRight") to = (at + 1) % order.length;
+    else if (event.key === "ArrowUp" || event.key === "ArrowLeft") to = (at - 1 + order.length) % order.length;
+    else if (event.key === "Home") to = 0;
+    else if (event.key === "End") to = order.length - 1;
+    if (to < 0) return;
+    event.preventDefault();
+    buttons.get(order[to]).focus();
+  });
+  paint();
+
+  return {
+    element: root,
+    model,
+    refresh: paint,
+    destroy() { unsubscribe(); root.remove(); if (ownModel) model.destroy(); },
+  };
+}

package/dist/layout-samples.js

@@ -0,0 +1,84 @@
+// Sample content for the layout editor's Preview (RR-99): a one-slide deck that uses the layout and fills each region with blocks of the
+// kinds it accepts, so the host's renderer can draw the layout as it will look. The blocks are the ones the Gallery draws its layout
+// previews with. Pure data; no DOM.
+import { clone } from "./layout-tree.js";
+import { LAYOUT_REGION_KINDS } from "./layout-templates.js";
+
+const PICTURE_SVG = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 160 100" width="1600" height="1000"><defs><linearGradient id="s" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#7aa7e6"/><stop offset="1" stop-color="#cfe0f5"/></linearGradient></defs><rect width="160" height="100" fill="url(#s)"/><path d="M0 62 Q40 40 80 58 T160 50 V100 H0 Z" fill="#3f8a55"/><path d="M0 78 Q50 64 100 76 T160 72 V100 H0 Z" fill="#2f6b42"/></svg>';
+const toBase64 = (text) => (typeof globalThis.btoa === "function" ? globalThis.btoa(text) : globalThis.Buffer.from(text).toString("base64"));
+/** A landscape picture as an SVG data URI. */
+export const SAMPLE_PICTURE = `data:image/svg+xml;base64,${toBase64(PICTURE_SVG)}`;
+
+const pick = (values, index) => values[index % values.length];
+
+/** The `index`-th sample block of a content kind; blocks of one region differ, so a preview reads as real content. */
+export function sampleBlock(kind, index = 0) {
+  switch (kind) {
+    case "text":
+      return { text: pick(["Revenue grew 18% on new accounts while churn held flat.", "Two field teams piloted the new workflow for six weeks.", "Support tickets fell by a third after the redesign."], index) };
+    case "list":
+      return { items: pick([["Close the audit gaps", "Pilot with two teams", "Report every week"], ["Hire two engineers", "Ship the mobile beta", "Retire the old portal"], ["Agree the budget", "Name the owners", "Review in March"]], index) };
+    case "image":
+      return { image: { src: SAMPLE_PICTURE, alt: pick(["Field team at work", "The new office", "Product in use"], index) } };
+    case "video":
+      return { video: { src: SAMPLE_PICTURE, alt: pick(["Product walkthrough", "Customer story", "Launch film"], index) } };
+    case "chart":
+      return { chart: { type: pick(["column", "line", "bar"], index), data: { columns: ["Quarter", "Current", "Baseline"], rows: [["Q1", 26 + index, 23], ["Q2", 30, 25 + index], ["Q3", 33 - index, 27], ["Q4", 37, 29]] } } };
+    case "table":
+      return { table: { columns: ["Workstream", "Owner", "Status"], rows: [["Compliance", "Program lead", "On track"], ["Reporting", "Analytics", "Watch"], ["Adoption", "Operations", "At risk"]] } };
+    case "code":
+      return { code: { language: "javascript", source: pick(["const total = items.reduce((sum, item) => sum + item.value, 0);\nconsole.log(total);", "export function share(part, whole) {\n  return whole ? part / whole : 0;\n}"], index) } };
+    case "metric":
+      return { metric: pick([{ value: "18%", label: "Net revenue growth", trend: "up" }, { value: "3.1M", label: "Active users", trend: "up" }, { value: "42", label: "Net promoter score", trend: "flat" }], index) };
+    case "quote":
+      return { quote: pick([{ text: "The plan makes the sequence of choices explicit.", attribution: "Program sponsor" }, { text: "We finally see the whole pipeline in one place.", attribution: "Sales lead" }], index) };
+    case "timeline":
+      return { timeline: { events: [{ when: "Q1", what: "Baseline" }, { when: "Q2", what: "Pilot" }, { when: "Q3", what: "Launch" }, { when: "Q4", what: "Scale" }] } };
+    case "group":
+      return { blocks: [sampleBlock("image", index), { text: pick(["Ana Ruiz, Chief Executive", "Sam Lee, Head of Product", "Kai Moreau, Engineering Lead"], index) }] };
+    default:
+      return sampleBlock("text", index);
+  }
+}
+
+/** The body regions of a record in reading order, as `{ name, region }`. */
+export function bodyRegions(record) {
+  const out = [];
+  const walk = (list) => {
+    for (const entry of Array.isArray(list) ? list : []) {
+      if (entry && Array.isArray(entry.regions) && entry.name === undefined) walk(entry.regions);
+      else if (entry && typeof entry.name === "string" && entry.name !== "title" && entry.name !== "subtitle") out.push({ name: entry.name, region: entry });
+    }
+  };
+  walk(record?.regions);
+  return out;
+}
+
+/** How many sample blocks a region gets: one for `flow: "none"`, else up to three (never more than its `max`). */
+export const regionSampleCount = (region) => (region?.flow === "none" ? 1 : Math.min(3, region?.max ?? 6));
+/** The kinds a region's samples cycle through: its `accepts`, or text, list and image when it accepts everything. */
+export const regionSampleKinds = (region) => (Array.isArray(region?.accepts) && region.accepts.length ? region.accepts.filter((kind) => LAYOUT_REGION_KINDS.includes(kind)) : ["text", "list", "image"]);
+
+/**
+ * A one-slide deck that uses `record` (embedded as a custom layout) with sample content pinned to every body region. The slide has a
+ * title and a subtitle, so the heading regions show as well.
+ */
+export function sampleDeck(record) {
+  const { $schema, id, ...layout } = clone(record);
+  void $schema;
+  const key = typeof id === "string" && /^[a-z][a-z0-9-]*$/.test(id) && id !== "auto" ? id : "layout-preview";
+  const blocks = [];
+  const used = {};
+  for (const { name, region } of bodyRegions(record)) {
+    const kinds = regionSampleKinds(region);
+    for (let count = 0; count < regionSampleCount(region); count++) {
+      const kind = kinds[count % kinds.length] ?? "text";
+      const index = used[kind] ?? 0;
+      used[kind] = index + 1;
+      blocks.push({ region: name, ...sampleBlock(kind, index) });
+    }
+  }
+  const slide = { layout: key, title: "Quarterly operating plan", subtitle: "Review for the leadership team" };
+  if (blocks.length) slide.blocks = blocks;
+  return { name: "Layout preview", catalogs: { custom: { layouts: { [key]: layout } } }, slides: [slide] };
+}

package/dist/layout-templates.d.ts

@@ -7,18 +7,42 @@ export declare const LAYOUT_REGION_KINDS: readonly string[];
 export declare const LAYOUT_REGION_ROLES: readonly string[];
 export declare const LAYOUT_REGION_FLOWS: readonly string[];
 export declare function groupLayoutChoices<T extends LayoutChoice>(choices: T[]): { name: string; choices: T[] }[];
-export interface GridLayoutInput {
+export declare const LAYOUT_DIRECTIONS: readonly ("row" | "column")[];
+export declare const LAYOUT_ANCHORS: readonly ("top" | "middle" | "bottom")[];
+/** Region lists nest at most this deep: the record's own list is level 1, a split's list level 2, a split inside it level 3. */
+export declare const LAYOUT_MAX_DEPTH: number;
+/** A list of regions (the record's, or a split's) holds at most this many entries. */
+export declare const LAYOUT_MAX_ENTRIES: number;
+export type LayoutSize = number | "auto";
+/** The rules of a body region; every one is optional (omitted `accepts`: every body content kind and `group`). */
+export interface LayoutRegionRules {
+  accepts?: string[];
+  role?: string;
+  flow?: string;
+  max?: number;
+  bleed?: boolean;
+  listColumns?: "auto" | 1;
+  anchor?: "top" | "middle" | "bottom";
+  empty?: "collapse" | "keep";
+}
+/** A region (`name`, `size`, rules); `title` and `subtitle` are heading regions that take only a size. */
+export interface LayoutRegionEntry extends LayoutRegionRules { name: string; size?: LayoutSize }
+/** A split: its own `regions`, laid out in `direction`. */
+export interface LayoutSplitEntry { direction: "row" | "column"; regions: (LayoutRegionEntry | LayoutSplitEntry)[]; size?: LayoutSize; anchor?: "top" | "middle" | "bottom" }
+export interface RegionLayoutInput {
   id: string;
   name: string;
   summary?: string;
-  cells: string[][];
-  regions: Record<string, { accepts: string[]; role?: string; flow?: string }>;
-  columns?: number[];
-  rows?: (number | "auto")[];
+  /** How the record's `regions` are placed: side by side (`row`) or stacked (`column`, the default). */
+  direction?: "row" | "column";
+  /** Applies to every region under the record unless a split or a region sets its own. */
+  anchor?: "top" | "middle" | "bottom";
+  regions: (LayoutRegionEntry | LayoutSplitEntry)[];
+  overflowRegion?: string;
 }
-export declare function layoutFromGrid(input: GridLayoutInput): { id: string; record: Record<string, unknown> };
-export declare function prepareCustomLayout(presentation: any, layout: { id: string; record: Record<string, unknown> }): { presentation: any; patches: JsonPatchOperation[]; id: string };
-export declare function saveCustomLayout(editor: EditorSession, layout: { id: string; record: Record<string, unknown> }): EditorChange;
+export declare function layoutFromRegions(input: RegionLayoutInput): { id: string; record: Record<string, unknown> };
+export declare function prepareCustomLayout(presentation: any, layout: { id: string; record: Record<string, unknown> }, options?: { replace?: boolean }): { presentation: any; patches: JsonPatchOperation[]; id: string };
+export declare function saveCustomLayout(editor: EditorSession, layout: { id: string; record: Record<string, unknown> }, options?: { replace?: boolean }): EditorChange;
 export declare function pinBlockToRegion(editor: EditorSession, slideIndex: number, blockIndex: number, region: string): EditorChange;
 
 export declare function layoutRegionSummary(record: unknown): string;

package/dist/layout-templates.js

@@ -1,6 +1,6 @@
-// OPF 0.19 layout authoring. The catalog owns records; this module owns only editor operations.
+// OPF layout authoring (FA-33: a record is one ordered list of regions, nested for 2D). The catalog owns records; this module owns only editor operations.
 import { resolveSlideContext } from "@openpresentation/opf";
-import { bindRegions, layoutStructure, layoutTemplate } from "@openpresentation/opf/composition";
+import { bindRegions, isLayoutTemplate, layoutStructure, layoutTemplate } from "@openpresentation/opf/composition";
 import { applyJsonPatch, createValuePatch, opfPathToJsonPointer } from "./index.js";
 import { checkedDocument, fail } from "./edit-helpers.js";
 import { checkFormat } from "./checks.js";
@@ -32,45 +32,97 @@ export function groupLayoutChoices(choices) {
   return groups;
 }
 
-/** Build the exact v2 record from a rectangular painted grid. `cells` is a row-major array of names or `.`. */
-export function layoutFromGrid({ id, name, summary, cells, regions, columns, rows }) {
-  if (!NAME.test(id) || id === "auto") throw fail("layout-id", "Choose a kebab-case layout id other than auto.");
-  if (typeof name !== "string" || !name.trim()) throw fail("layout-name", "Name the custom layout.");
-  if (!Array.isArray(cells) || cells.length < 1 || cells.length > 12 || !cells.every((row) => Array.isArray(row) && row.length === cells[0].length && row.length >= 1 && row.length <= 12))
-    throw fail("layout-grid", "Draw a rectangular grid of at most 12 by 12 cells.");
-  const areas = cells.map((row) => [...row]);
-  const names = new Set(cells.flat().filter((cell) => cell !== "."));
-  for (const area of names) if (!NAME.test(area) || (RESERVED.has(area) && area !== "title" && area !== "subtitle")) throw fail("layout-area", `Invalid area name: ${area}.`);
-  if (names.has("subtitle") && !names.has("title")) throw fail("layout-area", "A subtitle area needs a title area.");
-  const body = [...names].filter((area) => area !== "title" && area !== "subtitle");
-  for (const area of body) {
-    const points = cells.flatMap((row, y) => row.map((cell, x) => cell === area ? [x, y] : null).filter(Boolean));
-    const xs = points.map(([x]) => x), ys = points.map(([, y]) => y);
-    if (points.length !== (Math.max(...xs) - Math.min(...xs) + 1) * (Math.max(...ys) - Math.min(...ys) + 1))
-      throw fail("layout-area", `Area ${area} must fill one rectangle.`);
+/** Region lists nest at most this deep: the record's own list is level 1, a split's list level 2, a split inside it level 3. */
+export const LAYOUT_MAX_DEPTH = 3;
+/** A list of regions (the record's, or a split's) holds at most this many entries. */
+export const LAYOUT_MAX_ENTRIES = 12;
+export const LAYOUT_DIRECTIONS = Object.freeze(["row", "column"]);
+export const LAYOUT_ANCHORS = Object.freeze(["top", "middle", "bottom"]);
+const HEADINGS = new Set(["title", "subtitle"]);
+
+const validSize = (size) => size === "auto" || (typeof size === "number" && Number.isFinite(size) && size > 0 && size <= 100);
+
+/** One region's rules, checked and in the record's key order; `accepts` is optional (omitted: every body kind and group). */
+function regionRules(entry, name) {
+  const out = {};
+  if (entry.accepts !== undefined) {
+    if (!Array.isArray(entry.accepts) || !entry.accepts.length || entry.accepts.some((kind) => !LAYOUT_REGION_KINDS.includes(kind)))
+      throw fail("layout-region", `Choose accepted content kinds for ${name}.`);
+    out.accepts = [...new Set(entry.accepts)];
   }
-  if (body.length < 1) throw fail("layout-region", "Draw at least one content region.");
-  const selected = {};
-  for (const area of body) {
-    const input = regions?.[area];
-    if (!input || !Array.isArray(input.accepts) || !input.accepts.length || input.accepts.some((kind) => !LAYOUT_REGION_KINDS.includes(kind)))
-      throw fail("layout-region", `Choose accepted content kinds for ${area}.`);
-    if (input.role && !LAYOUT_REGION_ROLES.includes(input.role)) throw fail("layout-region", `Choose a valid role for ${area}.`);
-    if (input.flow && !LAYOUT_REGION_FLOWS.includes(input.flow)) throw fail("layout-region", `Choose a valid flow for ${area}.`);
-    selected[area] = { accepts: [...new Set(input.accepts)], ...(input.role ? { role: input.role } : {}), ...(input.flow ? { flow: input.flow } : {}) };
+  if (entry.role !== undefined) { if (!LAYOUT_REGION_ROLES.includes(entry.role)) throw fail("layout-region", `Choose a valid role for ${name}.`); out.role = entry.role; }
+  if (entry.flow !== undefined) { if (!LAYOUT_REGION_FLOWS.includes(entry.flow)) throw fail("layout-region", `Choose a valid flow for ${name}.`); out.flow = entry.flow; }
+  if (entry.max !== undefined) {
+    if (!Number.isInteger(entry.max) || entry.max < 1 || entry.max > 12) throw fail("layout-region", `The most blocks ${name} holds is a whole number from 1 to 12.`);
+    out.max = entry.max;
   }
-  const record = { name: name.trim(), areas, regions: selected };
+  if (entry.bleed !== undefined) { if (typeof entry.bleed !== "boolean") throw fail("layout-region", `Bleed for ${name} is true or false.`); out.bleed = entry.bleed; }
+  if (entry.listColumns !== undefined) { if (entry.listColumns !== "auto" && entry.listColumns !== 1) throw fail("layout-region", `List columns for ${name} is auto or 1.`); out.listColumns = entry.listColumns; }
+  if (entry.anchor !== undefined) { if (!LAYOUT_ANCHORS.includes(entry.anchor)) throw fail("layout-region", `Choose a valid anchor for ${name}.`); out.anchor = entry.anchor; }
+  if (entry.empty !== undefined) { if (entry.empty !== "collapse" && entry.empty !== "keep") throw fail("layout-region", `Empty for ${name} is collapse or keep.`); out.empty = entry.empty; }
+  return out;
+}
+
+/**
+ * Build the exact record from one ordered list of regions (OPF layout list form). `direction` ("row" or "column", default
+ * "column") lays the record's `regions` out; an entry is a region (`{ name, size?, ...rules }`) or a split (`{ direction,
+ * regions, size?, anchor? }`) that lays its own regions out in its own direction. Names are unique across the tree, `title`
+ * and `subtitle` are heading regions that take only a size, and `size` is a number above 0 up to 100 or `"auto"` (a child
+ * of a column only). The list is the reading order.
+ */
+export function layoutFromRegions({ id, name, summary, direction = "column", anchor, regions, overflowRegion }) {
+  if (!NAME.test(id) || id === "auto") throw fail("layout-id", "Choose a kebab-case layout id other than auto.");
+  if (typeof name !== "string" || !name.trim()) throw fail("layout-name", "Name the custom layout.");
+  if (!LAYOUT_DIRECTIONS.includes(direction)) throw fail("layout-direction", "Choose row or column for the direction.");
+  if (anchor !== undefined && !LAYOUT_ANCHORS.includes(anchor)) throw fail("layout-anchor", "Choose top, middle or bottom for the anchor.");
+  const names = new Set();
+  let body = 0;
+  const walk = (list, parent, depth) => {
+    if (!Array.isArray(list) || list.length < 1 || list.length > LAYOUT_MAX_ENTRIES)
+      throw fail("layout-regions", `A list holds 1 to ${LAYOUT_MAX_ENTRIES} regions and splits.`);
+    return list.map((entry) => {
+      if (entry === null || typeof entry !== "object" || Array.isArray(entry)) throw fail("layout-regions", "Each entry is a region or a split.");
+      const split = entry.name === undefined;
+      if (entry.size !== undefined && !validSize(entry.size)) throw fail("layout-size", `A size is a number above 0 up to 100, or auto${entry.name ? ` (${entry.name})` : ""}.`);
+      if (entry.size === "auto" && parent !== "column") throw fail("layout-size", `A size of auto is allowed only in a column${entry.name ? ` (${entry.name})` : ""}.`);
+      const size = entry.size === undefined ? {} : { size: entry.size };
+      if (split) {
+        if (!LAYOUT_DIRECTIONS.includes(entry.direction)) throw fail("layout-direction", "Choose row or column for each split.");
+        if (entry.anchor !== undefined && !LAYOUT_ANCHORS.includes(entry.anchor)) throw fail("layout-anchor", "Choose top, middle or bottom for the anchor.");
+        if (depth >= LAYOUT_MAX_DEPTH) throw fail("layout-depth", `Regions nest at most ${LAYOUT_MAX_DEPTH} levels deep.`);
+        return { direction: entry.direction, ...size, ...(entry.anchor ? { anchor: entry.anchor } : {}), regions: walk(entry.regions, entry.direction, depth + 1) };
+      }
+      if (typeof entry.name !== "string" || !NAME.test(entry.name)) throw fail("layout-area", `Invalid region name: ${entry.name}.`);
+      if (RESERVED.has(entry.name) && !HEADINGS.has(entry.name)) throw fail("layout-area", `Invalid region name: ${entry.name} is reserved.`);
+      if (names.has(entry.name)) throw fail("layout-area", `Region names are unique; ${entry.name} is used twice.`);
+      names.add(entry.name);
+      if (HEADINGS.has(entry.name)) {
+        const extra = Object.keys(entry).find((key) => key !== "name" && key !== "size");
+        if (extra) throw fail("layout-region", `${entry.name} is a heading region and takes only a size.`);
+        return { name: entry.name, ...size };
+      }
+      body++;
+      return { name: entry.name, ...size, ...regionRules(entry, entry.name) };
+    });
+  };
+  const list = walk(regions, direction, 1);
+  if (names.has("subtitle") && !names.has("title")) throw fail("layout-area", "A subtitle region needs a title region.");
+  if (body < 1) throw fail("layout-region", "Add at least one content region.");
+  if (overflowRegion !== undefined && (!names.has(overflowRegion) || HEADINGS.has(overflowRegion))) throw fail("layout-region", `${overflowRegion} is not a content region of this layout.`);
+  const record = { name: name.trim() };
   if (summary?.trim()) record.summary = summary.trim();
-  if (columns) record.columns = columns;
-  if (rows) record.rows = rows;
+  record.direction = direction;
+  if (anchor) record.anchor = anchor;
+  record.regions = list;
+  if (overflowRegion !== undefined) record.overflowRegion = overflowRegion;
   return { id, record };
 }
 
-/** Prepare one validated catalog edit. Existing custom ids are never silently overwritten. */
-export function prepareCustomLayout(presentation, layout) {
+/** Prepare one validated catalog edit. Existing custom ids are never silently overwritten, unless the caller says `replace: true` (editing a layout the deck already has). */
+export function prepareCustomLayout(presentation, layout, options = {}) {
   const { id, record } = layout;
   if (!NAME.test(id) || id === "auto") throw fail("layout-id", "Choose a kebab-case layout id other than auto.");
-  if (presentation.catalogs?.custom?.layouts?.[id]) throw fail("layout-exists", `A custom layout named ${id} already exists.`);
+  if (presentation.catalogs?.custom?.layouts?.[id] && !options.replace) throw fail("layout-exists", `A custom layout named ${id} already exists.`);
   const custom = presentation.catalogs?.custom ?? {};
   const next = { ...presentation, catalogs: { ...presentation.catalogs, custom: { ...custom, layouts: { ...custom.layouts, [id]: record } } } };
   const patches = [{ op: "replace", path: "", value: next }];
@@ -78,9 +130,9 @@ export function prepareCustomLayout(presentation, layout) {
   return { presentation: next, patches, id };
 }
 
-export function saveCustomLayout(editor, layout) {
-  const prepared = prepareCustomLayout(editor.presentation, layout);
-  return editor.applyPatch(prepared.patches, { source: "layout-grid", rejectInvalid: true });
+export function saveCustomLayout(editor, layout, options = {}) {
+  const prepared = prepareCustomLayout(editor.presentation, layout, options);
+  return editor.applyPatch(prepared.patches, { source: "layout-regions", rejectInvalid: true });
 }
 
 /** Pin a top-level block to a template region; the session validates the complete document. */
@@ -101,6 +153,6 @@ export function pinBlockToRegion(editor, slideIndex, blockIndex, region) {
 
 /** Region structure of a supported v2 template. */
 export function layoutRegionSummary(record) {
-  if (!Array.isArray(record?.areas)) return "";
+  if (!isLayoutTemplate(record)) return "";
   try { layoutTemplate(record); return layoutStructure(record); } catch { return "Invalid region template"; }
 }

package/dist/layout-tree.d.ts

@@ -0,0 +1,87 @@
+import type { LayoutRegionEntry, LayoutSplitEntry } from "./layout-templates.js";
+
+/** A layout record as the editor edits it: `id`, `name`, `direction`, `anchor`, the ordered `regions` list, and whatever else the record carries. */
+export interface LayoutRecord {
+  $schema?: string;
+  id?: string;
+  name?: string;
+  summary?: string;
+  direction?: "row" | "column";
+  anchor?: "top" | "middle" | "bottom";
+  regions: (LayoutRegionEntry | LayoutSplitEntry)[];
+  overflowRegion?: string;
+  design?: Record<string, unknown>;
+  composition?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+/** A region or split. */
+export type LayoutNode = LayoutRegionEntry | LayoutSplitEntry;
+/** Indexes from the record's own list down: `[]` is the record, `[1, 0]` is `regions[1].regions[0]`. */
+export type LayoutPath = number[];
+/** The result of an operation: a new record, and the paths to select afterwards (`null`: keep the selection). */
+export interface LayoutEdit { record: LayoutRecord; selection: LayoutPath[] | null }
+
+/** Thrown by an operation that refuses an edit; `message` says why. The record is never changed. */
+export declare class LayoutOperationError extends Error { code: string }
+export declare const HEADING_NAMES: readonly ["title", "subtitle"];
+export declare const REGION_KEYS: readonly string[];
+
+export declare const isSplit: (entry: unknown) => entry is LayoutSplitEntry;
+export declare const isRegion: (entry: unknown) => entry is LayoutRegionEntry;
+export declare const isHeading: (entry: unknown) => boolean;
+export declare function clone<T>(value: T): T;
+export declare function samePath(a: readonly number[], b: readonly number[]): boolean;
+export declare function isPrefix(prefix: readonly number[], path: readonly number[]): boolean;
+export declare function pathKey(path: readonly number[]): string;
+export declare function listAt(record: LayoutRecord, path: readonly number[]): LayoutNode[] | undefined;
+export declare function nodeAt(record: LayoutRecord, path: readonly number[]): LayoutNode | undefined;
+/** How the list that holds the node at `path` lays its entries out. */
+export declare function parentDirection(record: LayoutRecord, path: readonly number[]): "row" | "column";
+export declare function listDirection(record: LayoutRecord, listPath: readonly number[]): "row" | "column";
+/** The levels a node adds below its own list: 0 for a region, 1 plus the deepest child for a split. */
+export declare function height(entry: LayoutNode): number;
+export declare function nodes(record: LayoutRecord): { entry: LayoutNode; path: LayoutPath; listPath: LayoutPath; index: number; depth: number }[];
+export declare function regionNames(record: LayoutRecord): string[];
+export declare function pathOfName(record: LayoutRecord, name: string): LayoutPath | undefined;
+/** The size an entry has: its own, else `auto` for a heading in a column, else 1. */
+export declare function effectiveSize(entry: LayoutNode, direction: "row" | "column"): number | "auto";
+export declare function parseSize(value: unknown): number | "auto" | undefined;
+/** The anchor a node inherits from a split above it or the record (never its own). */
+export declare function inheritedAnchor(record: LayoutRecord, path: readonly number[]): { value: "top" | "middle" | "bottom" | undefined; from: "split" | "layout" | "default" };
+
+/** Split the region at `path` along `axis`; the original keeps its name and rules, the new region is `region-N`. */
+export declare function splitRegion(record: LayoutRecord, path: readonly number[], axis: "row" | "column"): LayoutEdit;
+/** Insert a new region into the list at `listPath`, before `index`. */
+export declare function insertRegion(record: LayoutRecord, listPath: readonly number[], index: number, entry?: LayoutNode): LayoutEdit;
+/** Add or remove the `title` or `subtitle` heading region. Removing a title removes the subtitle too. */
+export declare function toggleHeading(record: LayoutRecord, name: "title" | "subtitle"): LayoutEdit;
+/** Wrap sibling nodes in one new split. */
+export declare function wrapNodes(record: LayoutRecord, paths: readonly (readonly number[])[], axis: "row" | "column"): LayoutEdit;
+/** Replace a split with its children. */
+export declare function unwrapNode(record: LayoutRecord, path: readonly number[]): LayoutEdit;
+/** Remove nodes; a split left with one child collapses into it. */
+export declare function deleteNodes(record: LayoutRecord, paths: readonly (readonly number[])[]): LayoutEdit;
+export declare function duplicateNodes(record: LayoutRecord, paths: readonly (readonly number[])[]): LayoutEdit;
+/** Move nodes into the list at `targetListPath`, to position `index` of that list. */
+export declare function moveNodes(record: LayoutRecord, paths: readonly (readonly number[])[], targetListPath: readonly number[], index: number): LayoutEdit;
+/** Move a node one place earlier (-1) or later (1); at the end of a split it leaves the split. */
+export declare function reorderNode(record: LayoutRecord, path: readonly number[], delta: -1 | 1): LayoutEdit;
+/** Move a node into the neighboring split. */
+export declare function moveIntoSibling(record: LayoutRecord, path: readonly number[], delta: -1 | 1): LayoutEdit;
+/** Set or (with `undefined`) remove a property of the region or split at `path`. */
+export declare function setProperty(record: LayoutRecord, path: readonly number[], key: string, value: unknown): LayoutEdit;
+export declare function setLayoutProperty(record: LayoutRecord, key: "id" | "name" | "summary" | "direction" | "anchor" | "overflowRegion" | "design", value: unknown): LayoutEdit;
+export declare function removeDesignHint(record: LayoutRecord, key: string): LayoutEdit;
+/** The sizes of siblings `index` and `index + 1` when their divider sits at `fraction` of their joint length. Null for a pair with an `auto` side. */
+export declare function resizeSizes(record: LayoutRecord, listPath: readonly number[], index: number, fraction: number, options?: { free?: boolean }): { a: number; b: number; label: string } | null;
+export declare function setPairSizes(record: LayoutRecord, listPath: readonly number[], index: number, a: number, b: number): LayoutEdit;
+export declare function equalizePair(record: LayoutRecord, listPath: readonly number[], index: number): LayoutEdit;
+export declare function nudgePair(record: LayoutRecord, listPath: readonly number[], index: number, steps: number, big?: boolean): LayoutEdit;
+export declare function ratioLabel(a: number, b: number): string;
+
+export interface LayoutBox { x: number; y: number; w: number; h: number }
+export interface LayoutNodeBox extends LayoutBox { path: LayoutPath; entry: LayoutNode; kind: "region" | "split"; depth: number; direction: "row" | "column" }
+export interface LayoutDividerBox extends LayoutBox { listPath: LayoutPath; index: number; direction: "row" | "column"; draggable: boolean; depth: number; pairStart: number; pairLength: number; a: number | "auto"; b: number | "auto" }
+export interface LayoutSlotBox extends LayoutBox { listPath: LayoutPath; index: number; direction: "row" | "column"; depth: number }
+/** Place the tree in a unit box: a box per region and split, the dividers between siblings, the places a region can be inserted, and the band of the implicit title. */
+export declare function layoutBoxes(record: LayoutRecord, options?: { aspect?: number; gap?: number; autoShare?: number }): { nodes: LayoutNodeBox[]; dividers: LayoutDividerBox[]; slots: LayoutSlotBox[]; implicitTitle: LayoutBox | null };