@openpresentation/opf-editor 0.0.1 → 0.1.0

package/dist/data.d.ts

@@ -0,0 +1,2 @@
+export {parseTabularData, createDataContent, OPFDataImportError} from "@openpresentation/opf/data";
+export type {TabularData, DataImportOptions, DataContentOptions} from "@openpresentation/opf/data";

package/dist/data.js

@@ -0,0 +1 @@
+export {parseTabularData, createDataContent, OPFDataImportError} from "@openpresentation/opf/data";

package/dist/galleries.d.ts

@@ -0,0 +1,37 @@
+export interface GalleryOptions {
+  fetch?: typeof fetch;
+  signal?: AbortSignal;
+  base?: string;
+  origin?: string;
+}
+export interface GalleryItem {
+  id?: string;
+  name?: string;
+  description?: string;
+  category?: string;
+  url?: string;
+  raw?: unknown;
+}
+export interface OpfGallery {
+  name: string;
+  url: string;
+  items: GalleryItem[];
+}
+export declare function galleryUrl(input: string, base?: string): URL;
+export declare function normalizeGalleryUrl(
+  input: string,
+  base?: string,
+): string;
+export declare function galleryItemUrl(input: string, base?: string): string;
+export declare function fetchGalleryJson(
+  input: string,
+  options?: GalleryOptions,
+): Promise<any>;
+export declare function loadOpfGallery(
+  input: string,
+  options?: GalleryOptions,
+): Promise<OpfGallery>;
+export declare function loadOpfGalleryItem(
+  item: GalleryItem,
+  options?: GalleryOptions & { gallery?: string },
+): Promise<any>;

package/dist/galleries.js

@@ -0,0 +1,237 @@
+import { assertOpf, unwrapOpf, MAX_OPF_BYTES } from "./transfer.js";
+import { catalogs } from "@openpresentation/opf";
+export function galleryUrl(input, base) {
+  const url = new URL(input, base);
+  if (
+    !["http:", "https:"].includes(url.protocol) ||
+    url.username ||
+    url.password
+  )
+    throw new Error("Use a public HTTP or HTTPS URL without credentials.");
+  return url;
+}
+export function normalizeGalleryUrl(input, base) {
+  const url = galleryUrl(input, base);
+  if (url.hostname === "pptx.gallery") url.hostname = "www.pptx.gallery";
+  if (url.pathname === "/" || url.pathname === "")
+    url.pathname = "/registry.json";
+  return url.href;
+}
+export function galleryItemUrl(input, base) {
+  const url = galleryUrl(input, base);
+  if (["pptx.gallery", "www.pptx.gallery"].includes(url.hostname)) {
+    url.hostname = "www.pptx.gallery";
+    const match = url.pathname.match(
+      /^\/(layouts|color-schemes|colors|font-schemes|typography|themes|charts|backgrounds|narratives)\/([^/]+)\/?$/,
+    );
+    if (match)
+      url.pathname = `/registry/${{ colors: "color-schemes", typography: "font-schemes" }[match[1]] ?? match[1]}/${match[2]}.json`;
+    const content = url.pathname.match(
+      /^\/(blocks|image-treatments)\/([^/]+)\/?$/,
+    );
+    if (content) {
+      url.pathname = `/api/${content[1]}.json`;
+      url.hash = `opf-item=${encodeURIComponent(content[2])}`;
+    }
+  }
+  return url.href;
+}
+export async function fetchGalleryJson(
+  input,
+  { fetch: fetcher = globalThis.fetch, signal, base, origin } = {},
+) {
+  const url = galleryUrl(input, base);
+  if (origin && url.origin !== origin)
+    throw new Error(
+      "This item points outside its configured gallery. Load its URL explicitly to use it.",
+    );
+  const response = await fetcher(url.href, {
+    signal,
+    credentials: "omit",
+    referrerPolicy: "no-referrer",
+  });
+  if (!response.ok)
+    throw new Error(`Gallery returned HTTP ${response.status}.`);
+  if (origin && response.url && new URL(response.url).origin !== origin)
+    throw new Error(
+      "The gallery redirected to another origin. Add its destination explicitly.",
+    );
+  if (Number(response.headers?.get("content-length")) > MAX_OPF_BYTES)
+    throw new Error("Gallery response exceeds 20 MB.");
+  let text = "";
+  if (response.body?.getReader) {
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let count = 0;
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        count += value.byteLength;
+        if (count > MAX_OPF_BYTES)
+          throw new Error("Gallery response exceeds 20 MB.");
+        text += decoder.decode(value, { stream: true });
+      }
+      text += decoder.decode();
+    } catch (error) {
+      await reader.cancel();
+      throw error;
+    }
+  } else {
+    text = await response.text();
+    if (new TextEncoder().encode(text).length > MAX_OPF_BYTES)
+      throw new Error("Gallery response exceeds 20 MB.");
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(
+      "This URL did not return JSON. Use a gallery registry, OPF URL, or supported gallery item link.",
+    );
+  }
+}
+export async function loadOpfGallery(input, options = {}) {
+  const url = normalizeGalleryUrl(input, options.base);
+  const data = await fetchGalleryJson(url, options);
+  const entries = Array.isArray(data) ? data : (data.items ?? data.entries);
+  if (!Array.isArray(entries))
+    throw new Error(
+      "A gallery needs an items array. Use Load URL for a single OPF document.",
+    );
+  if (entries.length > 5000)
+    throw new Error("A gallery can contain at most 5,000 entries.");
+  return {
+    name: String(data.name ?? new URL(url).hostname),
+    url,
+    items: entries.map((item, index) => ({
+      id: String(item.id ?? item.slug ?? index),
+      name: String(
+        item.name ?? item.title ?? item.id ?? `Example ${index + 1}`,
+      ),
+      description: String(item.description ?? ""),
+      category: String(
+        item.category ?? item.type?.replace("registry:", "") ?? "Examples",
+      ),
+      url: item.registry_url ?? item.opfUrl ?? item.url,
+      raw: item,
+    })),
+  };
+}
+function attachDefinition(document, descriptor) {
+  const source = descriptor.metadata?.source,
+    category = descriptor.category ?? descriptor.metadata?.category;
+  if (!source) return;
+  const kind = {
+    layouts: "layouts",
+    "font-schemes": "fontSchemes",
+    "color-schemes": "colorSchemes",
+    themes: "themes",
+  }[category];
+  if (!kind) return;
+  const id = source.id ?? source.slug;
+  if (!id) return;
+  if (
+    catalogs[kind]?.some((record) => record.id === id) ||
+    document.catalogs?.[kind]?.records?.some((record) => record.id === id)
+  )
+    return;
+  let record;
+  if (kind === "layouts") {
+    const n = Math.min(
+      12,
+      Number(String(source.contentMultiple ?? "").replace("x", "")) || 1,
+    );
+    const type =
+      { Image: "picture", Chart: "chart", List: "list" }[source.contentType] ??
+      "text";
+    record = {
+      $schema: "https://openpresentation.org/schema/opf-layout/v1",
+      id,
+      name: source.label ?? source.name ?? id,
+      placeholders: [
+        { type: "title" },
+        ...Array.from({ length: n }, () => ({ type })),
+      ],
+      ...(n > 1
+        ? {
+            composition: {
+              mode: n <= 3 ? "row" : "grid",
+              ...(n > 3 ? { columns: 2 } : {}),
+            },
+          }
+        : {}),
+    };
+  } else if (kind === "fontSchemes")
+    record = {
+      $schema: "https://openpresentation.org/schema/opf-font-scheme/v1",
+      id,
+      name: source.name ?? id,
+      major: source.major ?? source.heading,
+      minor: source.minor ?? source.body,
+    };
+  else {
+    record = {
+      ...source,
+      $schema: `https://openpresentation.org/schema/opf-${kind === "themes" ? "theme" : "color-scheme"}/v1`,
+    };
+  }
+  document.catalogs ??= {};
+  document.catalogs[kind] ??= { records: [] };
+  document.catalogs[kind].records ??= [];
+  document.catalogs[kind].records.push(record);
+}
+export async function loadOpfGalleryItem(item, { gallery, ...options } = {}) {
+  const base = gallery ?? options.base;
+  const url = item.url ? galleryItemUrl(item.url, base) : base;
+  const origin = gallery ? new URL(gallery).origin : undefined;
+  let descriptor = item.url
+    ? await fetchGalleryJson(url, { ...options, base, origin })
+    : (item.raw ?? item);
+  if (url && new URL(url).hash.startsWith("#opf-item=")) {
+    const slug = decodeURIComponent(new URL(url).hash.slice(10));
+    descriptor = descriptor.items?.find(
+      (entry) => (entry.slug ?? entry.id) === slug,
+    );
+    if (!descriptor) throw new Error("This gallery item was not found.");
+  }
+  const document = structuredClone(unwrapOpf(descriptor));
+  if (!document?.slides)
+    throw new Error("This gallery item does not include a presentation.");
+  attachDefinition(document, descriptor);
+  // PPTX.gallery's older descriptors omit inline layout records. Resolve only named
+  // layout references from its known, same-origin registry; no arbitrary dependency crawl.
+  if (
+    url &&
+    ["www.pptx.gallery", "pptx.gallery"].includes(new URL(url).hostname)
+  ) {
+    const missing = [
+      ...new Set(
+        document.slides
+          .map((slide) => slide.layout)
+          .filter(
+            (id) =>
+              typeof id === "string" &&
+              !catalogs.layouts.some((record) => record.id === id) &&
+              !document.catalogs?.layouts?.records?.some(
+                (record) => record.id === id,
+              ),
+          ),
+      ),
+    ];
+    if (missing.length > 12)
+      throw new Error(
+        "This item needs too many layout definitions. Supply self-contained OPF.",
+      );
+    for (const id of missing) {
+      if (!/^[a-z][a-z0-9-]*$/.test(id))
+        throw new Error("Unsupported layout reference.");
+      const dependency = await fetchGalleryJson(
+        `/registry/layouts/${id}.json`,
+        { ...options, base: url, origin: new URL(url).origin },
+      );
+      attachDefinition(document, dependency);
+    }
+  }
+  assertOpf(document);
+  return document;
+}

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import type { PaginationOptions, PaginationResult } from "@openpresentation/opf/pagination";
+import type { Composition, ComposeSlideOptions, SlideComposition } from "@openpresentation/opf/composition";
 export declare const packageName = "@openpresentation/opf-editor";
 
 export declare const releaseLane: Readonly<{
@@ -18,7 +20,8 @@ export declare const runtimePolicy: Readonly<{
 export type JsonPatchOperation =
   | { op: "add"; path: string; value: unknown }
   | { op: "replace"; path: string; value: unknown }
-  | { op: "remove"; path: string };
+  | { op: "remove"; path: string }
+  | { op: "test"; path: string; value: unknown };
 
 export interface OPFValidationSummary {
   valid: boolean;
@@ -54,6 +57,9 @@ export interface EditorEvent {
 }
 
 export interface EditorSession {
+  paginateSlide(slideIndex: number, options?: PaginationOptions, meta?: Record<string, unknown>): { change: EditorChange | null; pagination: PaginationResult };
+  composeSlide(slideIndex: number, options?: ComposeSlideOptions): SlideComposition;
+  setComposition(slideIndex: number, composition: Composition, meta?: Record<string, unknown>): EditorChange;
   readonly document: unknown;
   readonly validation: OPFValidationSummary;
   readonly canUndo: boolean;
@@ -62,6 +68,7 @@ export interface EditorSession {
   subscribe(listener: (event: EditorEvent) => void): () => void;
   get(path: string | string[], fallback?: unknown): unknown;
   set(path: string | string[], value: unknown, meta?: Record<string, unknown>): EditorChange;
+  setGroupComposition(path: string, composition: Composition, meta?: Record<string, unknown>): EditorChange;
   setCatalog(path: string | string[], catalogKind: string, id: string, meta?: Record<string, unknown>): EditorChange;
   applyPatch(operations: JsonPatchOperation[], meta?: Record<string, unknown>): EditorChange;
   undo(meta?: Record<string, unknown>): EditorChange | null;

package/dist/index.js

@@ -1,9 +1,27 @@
+import { paginateSlide } from "@openpresentation/opf/pagination";
+import { composeSlide, resolveCanvasDimensions, resolveFontFamilies } from "@openpresentation/opf/composition";
 import {
   catalogKinds,
   catalogs as bundledCatalogs,
   validatePresentation
 } from "@openpresentation/opf";
 
+function resolveCompositionOptions(document, slideIndex, options = {}) {
+      const slide = document.slides?.[slideIndex];
+      if (!Number.isInteger(slideIndex) || !slide) throw new OPFEditorError("slide-index-out-of-range", "Slide index is out of range.");
+      const inline = document.catalogs?.layouts?.records ?? [];
+      const layout = options.layout ?? inline.find(record => record.id === slide.layout)
+        ?? bundledCatalogs.layouts.find(record => record.id === slide.layout);
+      const themeReference = slide.design?.theme ?? document.design?.theme ?? "minimal";
+      const themeId = typeof themeReference === "string" ? themeReference : themeReference.id;
+      const theme = document.catalogs?.themes?.records?.find(record => record.id === themeId)
+        ?? bundledCatalogs.themes.find(record => record.id === themeId);
+      const reference = slide.design?.fontScheme ?? document.design?.fontScheme ?? theme?.fontScheme ?? "roboto";
+      const id = typeof reference === "string" ? reference : reference.id;
+      const fontScheme = {...(document.catalogs?.fontSchemes?.records?.find(record=>record.id===id) ?? bundledCatalogs.fontSchemes.find(record=>record.id===id)),...(typeof reference === "object" ? reference : {})};
+      return { ...resolveCanvasDimensions(slide.design?.dimensions ?? document.design?.dimensions ?? theme?.dimensions), fonts:resolveFontFamilies(fontScheme), ...options, layout, slideIndex };
+}
+
 export const packageName = "@openpresentation/opf-editor";
 
 export const releaseLane = Object.freeze({
@@ -135,8 +153,10 @@ export function createEditorSession(input, options = {}) {
   const redoStack = [];
   const listeners = new Set();
   const rejectInvalid = Boolean(options.rejectInvalid);
+  let snapshotCache;
 
   function emit(event) {
+    snapshotCache = undefined;
     const snapshot = editor.snapshot();
     for (const listener of listeners) listener({ ...event, snapshot });
   }
@@ -156,6 +176,9 @@ export function createEditorSession(input, options = {}) {
       });
     }
 
+    if (patches.every(patch => patch.op === "test")) return {
+      document: clone(document), patches: clonePatchOperations(patches), inversePatches: [], validation: nextValidation
+    };
     document = next;
     validation = nextValidation;
     undoStack.push({ patches: clonePatchOperations(patches), inversePatches, meta });
@@ -190,14 +213,14 @@ export function createEditorSession(input, options = {}) {
       return redoStack.length > 0;
     },
     snapshot() {
-      return {
+      return snapshotCache ??= freezeSnapshot({
         document: clone(document),
-        validation,
+        validation: clone(validation),
         canUndo: undoStack.length > 0,
         canRedo: redoStack.length > 0,
         undoDepth: undoStack.length,
         redoDepth: redoStack.length
-      };
+      });
     },
     subscribe(listener) {
       if (typeof listener !== "function") {
@@ -215,6 +238,28 @@ export function createEditorSession(input, options = {}) {
         path: normalizePatchPath(path)
       });
     },
+    composeSlide(slideIndex, options = {}) {
+      return composeSlide(document.slides?.[slideIndex], resolveCompositionOptions(document, slideIndex, options));
+    },
+    paginateSlide(slideIndex, options = {}, meta = {}) {
+      const resolved = resolveCompositionOptions(document, slideIndex, options);
+      const pagination = paginateSlide(document.slides[slideIndex], { ...resolved, reservedIds: document.slides.map(slide => slide.id).filter(Boolean) });
+      if (pagination.slides.length === 1) return { change: null, pagination };
+      const slides = [...document.slides];
+      slides.splice(slideIndex, 1, ...pagination.slides);
+      const change = editor.set('slides', slides, { ...meta, rejectInvalid: true, pagination: pagination.pages });
+      return { change, pagination };
+    },
+    setComposition(slideIndex, composition, meta = {}) {
+      if (!Number.isInteger(slideIndex) || !document.slides?.[slideIndex]) throw new OPFEditorError("slide-index-out-of-range", "Slide index is out of range.");
+      return editor.set(`slides.${slideIndex}.composition`, composition, { ...meta, rejectInvalid: true });
+    },
+    setGroupComposition(path, composition, meta = {}) {
+      const pointer = normalizePatchPath(path);
+      const group = editor.get(pointer);
+      if (!pointer.startsWith("/slides/") || !group || !Array.isArray(group.blocks) || /^\/slides\/[^/]+$/.test(pointer)) throw new OPFEditorError("not-a-content-group", "Select a content group containing blocks.");
+      return editor.set(`${pointer}/composition`, composition, { ...meta, rejectInvalid: true });
+    },
     setCatalog(path, catalogKind, id, meta = {}) {
       return setCatalogId(editor, path, catalogKind, id, meta);
     },
@@ -301,10 +346,11 @@ export function createSvgTraceBinding(root, editor, options = {}) {
     if (options.interactive !== false) {
       ensureInteractiveTraceElement(element);
 
-      const onClick = (event) => select(element, event);
+      const onClick = (event) => { event.stopPropagation?.(); select(element, event); };
       const onKeydown = (event) => {
         if (event.key === "Enter" || event.key === " ") {
           event.preventDefault?.();
+          event.stopPropagation?.();
           select(element, event);
         }
       };
@@ -520,11 +566,13 @@ function normalizeOperation(operation) {
   if (!operation || typeof operation !== "object") {
     throw new OPFEditorError("invalid-patch-operation", "JSON Patch operation must be an object.", { operation });
   }
-  if (!["add", "replace", "remove"].includes(operation.op)) {
+  if (!["add", "replace", "remove", "test"].includes(operation.op)) {
     throw new OPFEditorError("unsupported-patch-operation", `Unsupported JSON Patch operation: ${operation.op}.`, {
       operation
     });
   }
+  if (operation.op === "test" && !Object.prototype.hasOwnProperty.call(operation, "value"))
+    throw new OPFEditorError("invalid-patch-operation", "A test operation requires a value.");
   const normalized = {
     op: operation.op,
     path: normalizePatchPath(operation.path)
@@ -556,8 +604,20 @@ function readAtPath(document, segments) {
   return current;
 }
 
+function jsonEqual(a, b) {
+  if (a === b) return true;
+  if (a === null || b === null || typeof a !== "object" || typeof b !== "object" || Array.isArray(a) !== Array.isArray(b)) return false;
+  const keys = Object.keys(a);
+  return keys.length === Object.keys(b).length && keys.every(key => Object.prototype.hasOwnProperty.call(b, key) && jsonEqual(a[key], b[key]));
+}
 function applyJsonPatchOperation(document, operation) {
   const segments = parseJsonPointer(operation.path);
+  if (operation.op === "test") {
+    const current = readAtPath(document, segments);
+    if (current === MISSING || !jsonEqual(current, operation.value))
+      throw new OPFEditorError("patch-test-failed", `The value changed at ${operation.path || "/"}.`, {path: operation.path});
+    return clone(document);
+  }
   if (segments.length === 0) {
     if (operation.op === "remove") return undefined;
     return clone(operation.value);
@@ -596,6 +656,9 @@ function pathParentIsArray(document, path) {
 }
 
 function applyArrayOperation(parent, key, operation) {
+  if (!/^(0|[1-9][0-9]*)$/.test(key) && !(key === "-" && operation.op === "add")) {
+    throw new OPFEditorError("invalid-array-index", `Invalid array index in patch path ${operation.path}.`, { path: operation.path });
+  }
   const index = key === "-" ? parent.length : Number(key);
   if (!Number.isInteger(index) || index < 0 || index > parent.length) {
     throw new OPFEditorError("invalid-array-index", `Invalid array index in patch path ${operation.path}.`, {
@@ -622,7 +685,7 @@ function applyArrayOperation(parent, key, operation) {
 
 function applyObjectOperation(parent, key, operation) {
   if (operation.op === "add") {
-    parent[key] = clone(operation.value);
+    Object.defineProperty(parent, key, { value: clone(operation.value), writable: true, enumerable: true, configurable: true });
     return;
   }
 
@@ -707,3 +770,11 @@ function resolveDomDocument(documentRef) {
   }
   return resolved;
 }
+
+function freezeSnapshot(value) {
+  if (value && typeof value === "object" && !Object.isFrozen(value)) {
+    Object.values(value).forEach(freezeSnapshot);
+    Object.freeze(value);
+  }
+  return value;
+}

package/dist/layout-handles.js

@@ -0,0 +1,116 @@
+import {prepareTrackResize} from './layout.js';
+import {getValueAtPath} from './index.js';
+
+export function createLayoutHandles(root, options) {
+  const doc=root.ownerDocument,win=doc.defaultView,editor=options.editor;
+  const layer=doc.createElement('div');
+  layer.className='opf-layout-handles';
+  layer.style.cssText='position:absolute;inset:0;pointer-events:none;z-index:3';
+  root.append(layer);
+  let enabled=options.enabled??false,active=null,committing=false,frame=0,lastGeometry;
+  const signature=(path)=>JSON.stringify(editor.get(path));
+  const trackData=flow=>flow.composition.mode==='column'?{axis:'y',size:'height',tracks:flow.rows}:{axis:'x',size:'width',tracks:flow.columns};
+  function renderCanonical(){options.render();}
+  function release(edit){if(edit?.pointerId!==undefined&&layer.hasPointerCapture(edit.pointerId))layer.releasePointerCapture(edit.pointerId);}
+  function cancel(clear=true) {
+    if(!active)return;
+    const edit=active;active=null;if(frame)win.cancelAnimationFrame(frame);frame=0;release(edit);
+    renderCanonical();if(clear)options.onCancel?.({path:edit.flow.path});
+  }
+  function preview(fraction) {
+    if(!active)return false;
+    const edit=active;
+    edit.fraction=fraction;
+    try{
+      const prepared=prepareTrackResize(editor.document,active.flow,active.boundary,fraction);
+      options.render(prepared.document);
+      if(active!==edit)return false;
+      edit.prepared=prepared;edit.valid=true;
+      options.onDraft?.({document:prepared.document,path:active.flow.path+'.composition',value:prepared.composition});
+      if(active!==edit)return false;
+      options.clearError?.();return true;
+    }catch(error){if(active===edit)edit.valid=false;options.onError(error);return false;}
+  }
+  function commit() {
+    if(!active)return true;
+    if(frame){win.cancelAnimationFrame(frame);frame=0;preview(active.fraction);}
+    if(!active)return false;
+    const edit=active;
+    if(signature(edit.flow.path)!==edit.base){cancel(false);options.onError(new Error('The layout changed elsewhere. The resize was cancelled.'));return false;}
+    if(!edit.valid){cancel(false);return false;}
+    active=null;release(edit);committing=true;
+    try{
+      // Rebase unrelated document edits, retaining the guarded container.
+      const prepared=prepareTrackResize(editor.document,edit.flow,edit.boundary,edit.fraction);
+      if(edit.moved)editor.applyPatch(prepared.patches,{source:'canvas-layout',rejectInvalid:true});
+      else renderCanonical();
+      options.onCommit?.({path:edit.flow.path+'.composition',editor});return true;
+    }catch(error){renderCanonical();options.onError(error);return false;}
+    finally{committing=false;}
+  }
+  function begin(flow,boundary,event) {
+    if(!options.beforeEdit())return false;
+    if(active&&!commit())return false;
+    const {axis,tracks}=trackData(flow),a=tracks[boundary],b=tracks[boundary+1];
+    active={flow:structuredClone(flow),boundary,base:signature(flow.path),fraction:a.size/(a.size+b.size),initial:a.size/(a.size+b.size),pair:a.size+b.size,axis,valid:true,moved:false,pointerId:event?.pointerId,origin:event?(axis==='x'?event.clientX:event.clientY):0};
+    if(event)layer.setPointerCapture(event.pointerId);
+    return true;
+  }
+  function update(document,geometry) {
+    lastGeometry=geometry;
+    layer.replaceChildren();
+    if(!enabled||options.isTextEditing())return;
+    for(const flow of geometry.flows??[]){
+      const {axis,size,tracks}=trackData(flow);
+      if(tracks.length<2||tracks.length>12||flow.itemCount!==flow.slotCount)continue;
+      for(let boundary=0;boundary<tracks.length-1;boundary++){
+        const track=tracks[boundary],next=tracks[boundary+1],vertical=axis==='x';
+        const node=doc.createElement('div');node.tabIndex=0;node.setAttribute('role','separator');
+        node.dataset.layoutPath=flow.path;node.dataset.layoutBoundary=String(boundary);
+        node.setAttribute('aria-label',`Resize ${flow.path} ${vertical?'columns':'rows'} ${boundary+1} and ${boundary+2}`);
+        node.setAttribute('aria-orientation',vertical?'vertical':'horizontal');
+        node.setAttribute('aria-valuemin','5');node.setAttribute('aria-valuemax','95');
+        node.setAttribute('aria-valuenow',String(Math.round(100*track.size/(track.size+next.size))));
+        node.setAttribute('aria-valuetext',`${Math.round(100*track.size/(track.size+next.size))}% of adjacent tracks`);
+        node.title='Drag to resize · Arrow keys adjust · Shift adjusts faster · Esc cancels';
+        const at=flow.box[axis]+track.offset+track.size+flow.gap/2;
+        node.style.cssText=`position:absolute;pointer-events:auto;touch-action:none;cursor:${vertical?'col':'row'}-resize;box-sizing:border-box;border-radius:5px;background:#8a78d733;outline-offset:2px;${vertical?`left:calc(${at/geometry.width*100}% - 5px);top:${flow.box.y/geometry.height*100}%;width:10px;height:${flow.box.height/geometry.height*100}%`:`top:calc(${at/geometry.height*100}% - 5px);left:${flow.box.x/geometry.width*100}%;height:10px;width:${flow.box.width/geometry.width*100}%`}`;
+        const grip=doc.createElement('span');grip.style.cssText=`position:absolute;border-radius:2px;background:#8170d5;${vertical?'left:4px;top:0;bottom:0;width:2px':'top:4px;left:0;right:0;height:2px'}`;node.append(grip);
+        node.onpointerdown=event=>{if(event.button!==0)return;event.preventDefault();event.stopPropagation();try{begin(flow,boundary,event);}catch(error){options.onError(error);}};
+        node.onkeydown=event=>{
+          const keys=vertical?['ArrowLeft','ArrowRight']:['ArrowUp','ArrowDown'];
+          if(event.key==='Escape'){event.preventDefault();cancel();return;}
+          if(!keys.includes(event.key)&&!['Home','End'].includes(event.key))return;
+          event.preventDefault();event.stopPropagation();
+          if(!begin(flow,boundary))return;
+          active.moved=true;
+          const fraction=event.key==='Home' ? .05 : event.key==='End' ? .95 : active.initial+(event.key===keys[1]?1:-1)*(event.shiftKey ? .05 : .01);
+          preview(Math.max(0,Math.min(1,fraction)));commit();
+          [...layer.children].find(child=>child.dataset.layoutPath===flow.path&&child.dataset.layoutBoundary===String(boundary))?.focus();
+        };
+        layer.append(node);
+      }
+    }
+  }
+  layer.addEventListener('pointermove',event=>{
+    if(!active||event.pointerId!==active.pointerId)return;
+    const svg=root.querySelector('.opf-canvas-preview svg'),rect=svg.getBoundingClientRect();
+    const scale=rect.width/(lastGeometry?.width??1280);
+    const current=active.axis==='x'?event.clientX:event.clientY;
+    active.fraction=Math.max(0,Math.min(1,active.initial+(current-active.origin)/(scale*active.pair)));
+    if(Math.abs(current-active.origin)<1&&!active.moved)return;
+    active.moved=true;if(frame)win.cancelAnimationFrame(frame);
+    frame=win.requestAnimationFrame(()=>{frame=0;if(active)preview(active.fraction);});
+  });
+  layer.addEventListener('pointerup',event=>{if(active?.pointerId===event.pointerId)commit();});
+  layer.addEventListener('pointercancel',event=>{if(active?.pointerId===event.pointerId)cancel();});
+  layer.addEventListener('lostpointercapture',event=>{if(active?.pointerId===event.pointerId)cancel();});
+  const escape=event=>{if(event.key==='Escape'&&active){event.preventDefault();event.stopPropagation();cancel();}};
+  doc.addEventListener('keydown',escape,true);
+  const unsubscribe=editor.subscribe(()=>{
+    if(committing||!active)return;
+    if(signature(active.flow.path)!==active.base){cancel(false);options.onError(new Error('The layout changed elsewhere. The resize was cancelled.'));}
+    else preview(active.fraction);
+  });
+  return {update,commit,cancel,hide(){layer.replaceChildren();},get editingPath(){return active?.flow.path??null;},get enabled(){return enabled;},setEnabled(value){if(!commit())return false;enabled=!!value;renderCanonical();return true;},destroy(){if(frame)win.cancelAnimationFrame(frame);active=null;unsubscribe();doc.removeEventListener('keydown',escape,true);layer.remove();}};
+}

package/dist/layout.d.ts

@@ -0,0 +1,10 @@
+import type {ComposedFlow, Composition} from '@openpresentation/opf/composition';
+import type {JsonPatchOperation} from './index.js';
+/** Resize adjacent tracks. Fractions clamp to 5–95%; automatic flows become explicit grids. */
+export declare function prepareTrackResize(document:unknown,flow:ComposedFlow,boundary:number,fraction:number):{
+  document:unknown;patches:JsonPatchOperation[];composition:Composition;fraction:number;
+};
+
+export {prepareBlockMove,listBlockContainers,prepareBlockInsert,prepareBlockDuplicate,prepareBlockRemove,createContentBlock} from './blocks.js';
+
+export type {PreparedBlockChange,ContentBlockKind} from './blocks.js';

package/dist/layout.js

@@ -0,0 +1,34 @@
+import {getValueAtPath, createValuePatch, applyJsonPatch, validateOpfDocument, opfPathToJsonPointer} from './index.js';
+
+/** Prepare a validated track resize; the test operation guards its container revision. */
+export function prepareTrackResize(document, flow, boundary, fraction) {
+  const vertical = flow?.composition?.mode === 'column';
+  const tracks = vertical ? flow?.rows : flow?.columns;
+  if (!Array.isArray(tracks) || tracks.length < 2 || tracks.length > 12)
+    throw new RangeError('Resize a flow with 2–12 tracks; group larger arrangements first.');
+  if (flow.itemCount !== flow.slotCount)
+    throw new RangeError('Choose an explicit arrangement before resizing reserved layout slots.');
+  if (!Number.isInteger(boundary) || boundary < 0 || boundary >= tracks.length - 1)
+    throw new RangeError('Track boundary is out of range.');
+  if (!Number.isFinite(fraction) || fraction < 0 || fraction > 1)
+    throw new RangeError('Track fraction must be between zero and one.');
+  const container = getValueAtPath(document,flow.path);
+  if (!container || typeof container !== 'object') throw new Error('The layout container no longer exists.');
+  const effective = flow.composition.weights ?? [];
+  const weights = Array.from({length:Math.max(tracks.length,effective.length)},(_,index)=>effective[index]??1);
+  if (weights.some(weight=>!Number.isFinite(weight)||weight<=0||weight>100)) throw new RangeError('Invalid track weights.');
+  const share = Math.min(.95,Math.max(.05,fraction));
+  const pair = weights[boundary]+weights[boundary+1];
+  weights[boundary]=pair*share;weights[boundary+1]=pair*(1-share);
+  const scale = Math.max(1,...weights.slice(0,tracks.length).map(weight=>weight/100));
+  for(let i=0;i<tracks.length;i++)weights[i]=Number((weights[i]/scale).toPrecision(12));
+  const composition={...container.composition,mode:flow.composition.mode??'auto',weights};
+  // A drag expresses an explicit arrangement. Preserve the automatic engine's chosen columns.
+  if(composition.mode==='auto'){composition.mode='grid';composition.columns=flow.columns.length;}
+  const patches=[{op:'test',path:opfPathToJsonPointer(flow.path),value:structuredClone(container)},...createValuePatch(document,[...flow.path.split('.'),'composition'],composition)];
+  const next=applyJsonPatch(document,patches),validation=validateOpfDocument(next);
+  if(!validation.valid)throw new Error(validation.errors[0]?.message??'Track resize is not valid OPF.');
+  return {document:next,patches,composition,fraction:share};
+}
+
+export {prepareBlockMove,listBlockContainers,prepareBlockInsert,prepareBlockDuplicate,prepareBlockRemove,createContentBlock} from './blocks.js';