@openpresentation/opf-editor 0.27.0 → 0.28.0

package/dist/studio-kit/dom.js

@@ -0,0 +1,162 @@
+// CE-18, the studio kit: DOM helpers every studio part shares. `createDom` binds element, icon and button factories to one document and
+// one class prefix (Layout Studio passes "opf-lx", so its classes are unchanged), the inline Lucide icons, `openMenu` (the menu behind every
+// context menu), the typing-target guard of the shortcuts, and small formatting helpers. Plain DOM; no network; nothing about a document
+// format.
+
+// Lucide icons (ISC license), as path data.
+export const ICONS = {
+  MousePointer2: '<path d="M4.037 4.688a.495.495 0 0 1 .651-.651l16 6.5a.5.5 0 0 1-.063.947l-6.124 1.58a2 2 0 0 0-1.438 1.435l-1.579 6.126a.5.5 0 0 1-.947.063z"/>',
+  Columns2: '<rect width="18" height="18" x="3" y="3" rx="2"/><path d="M12 3v18"/>',
+  Rows2: '<rect width="18" height="18" x="3" y="3" rx="2"/><path d="M3 12h18"/>',
+  Plus: '<path d="M5 12h14"/><path d="M12 5v14"/>',
+  Heading: '<path d="M6 12h12"/><path d="M6 20V4"/><path d="M18 20V4"/>',
+  Hand: '<path d="M18 11V6a2 2 0 0 0-2-2a2 2 0 0 0-2 2"/><path d="M14 10V4a2 2 0 0 0-2-2a2 2 0 0 0-2 2v2"/><path d="M10 10.5V6a2 2 0 0 0-2-2a2 2 0 0 0-2 2v8"/><path d="M18 8a2 2 0 1 1 4 0v6a8 8 0 0 1-8 8h-2c-2.8 0-4.5-.86-5.99-2.34l-3.6-3.6a2 2 0 0 1 2.83-2.82L7 15"/>',
+  Eye: '<path d="M2.062 12.348a1 1 0 0 1 0-.696 10.75 10.75 0 0 1 19.876 0 1 1 0 0 1 0 .696 10.75 10.75 0 0 1-19.876 0"/><circle cx="12" cy="12" r="3"/>',
+  Undo2: '<path d="M9 14 4 9l5-5"/><path d="M4 9h10.5a5.5 5.5 0 0 1 5.5 5.5a5.5 5.5 0 0 1-5.5 5.5H11"/>',
+  Redo2: '<path d="m15 14 5-5-5-5"/><path d="M20 9H9.5A5.5 5.5 0 0 0 4 14.5A5.5 5.5 0 0 0 9.5 20H13"/>',
+  ChevronRight: '<path d="m9 18 6-6-6-6"/>',
+  ChevronDown: '<path d="m6 9 6 6 6-6"/>',
+  X: '<path d="M18 6 6 18"/><path d="m6 6 12 12"/>',
+  Check: '<path d="M20 6 9 17l-5-5"/>',
+  CircleX: '<circle cx="12" cy="12" r="10"/><path d="m15 9-6 6"/><path d="m9 9 6 6"/>',
+  Info: '<circle cx="12" cy="12" r="10"/><path d="M12 16v-4"/><path d="M12 8h.01"/>',
+  Trash2: '<path d="M3 6h18"/><path d="M19 6v14c0 1-1 2-2 2H7c-1 0-2-1-2-2V6"/><path d="M8 6V4c0-1 1-2 2-2h4c1 0 2 1 2 2v2"/><line x1="10" x2="10" y1="11" y2="17"/><line x1="14" x2="14" y1="11" y2="17"/>',
+  Copy: '<rect width="14" height="14" x="8" y="8" rx="2" ry="2"/><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"/>',
+  GripVertical: '<circle cx="9" cy="12" r="1"/><circle cx="9" cy="5" r="1"/><circle cx="9" cy="19" r="1"/><circle cx="15" cy="12" r="1"/><circle cx="15" cy="5" r="1"/><circle cx="15" cy="19" r="1"/>',
+  ZoomIn: '<circle cx="11" cy="11" r="8"/><line x1="21" x2="16.65" y1="21" y2="16.65"/><line x1="11" x2="11" y1="8" y2="14"/><line x1="8" x2="14" y1="11" y2="11"/>',
+  ZoomOut: '<circle cx="11" cy="11" r="8"/><line x1="21" x2="16.65" y1="21" y2="16.65"/><line x1="8" x2="14" y1="11" y2="11"/>',
+  Maximize: '<path d="M8 3H5a2 2 0 0 0-2 2v3"/><path d="M21 8V5a2 2 0 0 0-2-2h-3"/><path d="M3 16v3a2 2 0 0 0 2 2h3"/><path d="M16 21h3a2 2 0 0 0 2-2v-3"/>',
+  Square: '<rect width="18" height="18" x="3" y="3" rx="2"/>',
+  Layers: '<path d="M12.83 2.18a2 2 0 0 0-1.66 0L2.6 6.08a1 1 0 0 0 0 1.83l8.58 3.91a2 2 0 0 0 1.66 0l8.58-3.9a1 1 0 0 0 0-1.83z"/><path d="m22 17.65-9.17 4.16a2 2 0 0 1-1.66 0L2 17.65"/><path d="m22 12.65-9.17 4.16a2 2 0 0 1-1.66 0L2 12.65"/>',
+  Pencil: '<path d="M21.174 6.812a1 1 0 0 0-3.986-3.987L3.842 16.174a2 2 0 0 0-.5.83l-1.321 4.352a.5.5 0 0 0 .623.622l4.353-1.32a2 2 0 0 0 .83-.497z"/><path d="m15 5 4 4"/>',
+  Unfold: '<path d="m7 15 5 5 5-5"/><path d="m7 9 5-5 5 5"/>',
+  BetweenHorizontalStart: '<rect width="13" height="7" x="8" y="3" rx="1"/><path d="m2 9 3 3-3 3"/><rect width="13" height="7" x="8" y="14" rx="1"/>',
+  AlignLeft: '<path d="M15 12H3"/><path d="M17 18H3"/><path d="M21 6H3"/>',
+  List: '<path d="M3 12h.01"/><path d="M3 18h.01"/><path d="M3 6h.01"/><path d="M8 12h13"/><path d="M8 18h13"/><path d="M8 6h13"/>',
+  Image: '<rect width="18" height="18" x="3" y="3" rx="2" ry="2"/><circle cx="9" cy="9" r="2"/><path d="m21 15-3.086-3.086a2 2 0 0 0-2.828 0L6 21"/>',
+  Play: '<polygon points="6 3 20 12 6 21 6 3"/>',
+  ChartColumn: '<path d="M3 3v16a2 2 0 0 0 2 2h16"/><path d="M18 17V9"/><path d="M13 17V5"/><path d="M8 17v-3"/>',
+  Table: '<path d="M12 3v18"/><rect width="18" height="18" x="3" y="3" rx="2"/><path d="M3 9h18"/><path d="M3 15h18"/>',
+  Code: '<polyline points="16 18 22 12 16 6"/><polyline points="8 6 2 12 8 18"/>',
+  Hash: '<line x1="4" x2="20" y1="9" y2="9"/><line x1="4" x2="20" y1="15" y2="15"/><line x1="10" x2="8" y1="3" y2="21"/><line x1="16" x2="14" y1="3" y2="21"/>',
+  Quote: '<path d="M16 3a2 2 0 0 0-2 2v6a2 2 0 0 0 2 2 1 1 0 0 1 1 1v1a2 2 0 0 1-2 2 1 1 0 0 0-1 1v2a1 1 0 0 0 1 1 6 6 0 0 0 6-6V5a2 2 0 0 0-2-2z"/><path d="M5 3a2 2 0 0 0-2 2v6a2 2 0 0 0 2 2 1 1 0 0 1 1 1v1a2 2 0 0 1-2 2 1 1 0 0 0-1 1v2a1 1 0 0 0 1 1 6 6 0 0 0 6-6V5a2 2 0 0 0-2-2z"/>',
+  GitCommitHorizontal: '<circle cx="12" cy="12" r="3"/><line x1="3" x2="9" y1="12" y2="12"/><line x1="15" x2="21" y1="12" y2="12"/>',
+  Group: '<path d="M3 7V5c0-1.1.9-2 2-2h2"/><path d="M17 3h2c1.1 0 2 .9 2 2v2"/><path d="M21 17v2c0 1.1-.9 2-2 2h-2"/><path d="M7 21H5c-1.1 0-2-.9-2-2v-2"/><rect width="7" height="5" x="7" y="7" rx="1"/><rect width="7" height="5" x="10" y="12" rx="1"/>',
+};
+
+const SVG = "http://www.w3.org/2000/svg";
+let serial = 0;
+/** A unique id for this page: `prefix-1`, `prefix-2`... (one counter for every part, so ids never collide across parts). */
+export const nextId = (prefix) => `${prefix}-${++serial}`;
+
+/** The default class prefix of kit parts; Layout Studio passes "opf-lx". */
+export const KIT_PREFIX = "opf-kit";
+
+/**
+ * DOM helpers bound to one document and one class prefix: `el(tag, className, attributes)` (`text` sets the text; `undefined`, `null` and
+ * `false` attributes are skipped), `icon(name, size)` (an inline Lucide icon, `aria-hidden`), and `button(className, options)` (a real
+ * button; with a `label` and only an icon, the label is its accessible name).
+ */
+export function createDom(doc, { prefix = KIT_PREFIX } = {}) {
+  const el = (tag, className, attributes = {}) => {
+    const node = doc.createElement(tag);
+    if (className) node.className = className;
+    for (const [key, value] of Object.entries(attributes)) {
+      if (value === undefined || value === null || value === false) continue;
+      if (key === "text") node.textContent = value; else node.setAttribute(key, value === true ? "" : String(value));
+    }
+    return node;
+  };
+  const icon = (name, size = 16) => {
+    const svg = doc.createElementNS(SVG, "svg");
+    svg.setAttribute("viewBox", "0 0 24 24");
+    svg.setAttribute("width", String(size));
+    svg.setAttribute("height", String(size));
+    svg.setAttribute("fill", "none");
+    svg.setAttribute("stroke", "currentColor");
+    svg.setAttribute("stroke-width", "2");
+    svg.setAttribute("stroke-linecap", "round");
+    svg.setAttribute("stroke-linejoin", "round");
+    svg.setAttribute("aria-hidden", "true");
+    svg.setAttribute("focusable", "false");
+    svg.setAttribute("class", `${prefix}-icon ${prefix}-icon-${name.toLowerCase()}`);
+    svg.innerHTML = ICONS[name] ?? "";
+    return svg;
+  };
+  const button = (className, { label, text, iconName, size = 16, pressed, title, attributes = {} } = {}) => {
+    const node = el("button", className, { type: "button", "aria-label": label, title: title ?? (text ? undefined : label), ...attributes });
+    if (pressed !== undefined) node.setAttribute("aria-pressed", String(pressed));
+    if (iconName) node.append(icon(iconName, size));
+    if (text) node.append(el("span", `${prefix}-button-text`, { text }));
+    return node;
+  };
+  return { doc, prefix, el, icon, button };
+}
+
+/** Whether keyboard events from this element belong to a field the person is typing in (so a shortcut must not fire). */
+export function isTypingTarget(target) {
+  if (!target || target.nodeType !== 1) return false;
+  const tag = target.tagName;
+  if (tag === "TEXTAREA" || tag === "SELECT") return true;
+  if (tag === "INPUT") return !["checkbox", "radio", "button", "submit", "reset"].includes(target.type);
+  return target.isContentEditable === true;
+}
+export const isMac = (win) => /Mac|iPhone|iPad/.test(win?.navigator?.platform ?? "");
+
+/** A unit fraction as a CSS percentage, rounded to 0.01%. */
+export const pct = (fraction) => `${Math.round(fraction * 10000) / 100}%`;
+
+/**
+ * A menu (`role="menu"`) at a client point, inside `host` (a positioned element). Items are `{ label, onSelect, disabled, role, checked, hint }`.
+ * Arrow keys, Home, End, Enter and Space work; Escape closes and returns focus to `returnFocus`; a press outside closes it. Returns
+ * `{ element, close }`.
+ */
+export function openMenu(dom, host, { x, y, items, label, returnFocus, onClose, className = "" }) {
+  const p = dom.prefix;
+  const menu = dom.el("div", `${p}-menu ${className}`.trim(), { role: "menu", "aria-label": label });
+  const buttons = items.map((item) => {
+    const role = item.role ?? "menuitem";
+    const node = dom.el("button", `${p}-menuitem`, { type: "button", role, tabindex: "-1", "aria-disabled": item.disabled ? "true" : undefined, "aria-checked": role === "menuitemcheckbox" ? String(Boolean(item.checked)) : undefined });
+    node.append(dom.el("span", `${p}-menu-label`, { text: item.label }));
+    if (item.hint) node.append(dom.el("span", `${p}-menu-hint`, { text: item.hint }));
+    if (role === "menuitemcheckbox") node.prepend(dom.icon(item.checked ? "Check" : "Square", 14));
+    node.addEventListener("click", () => {
+      if (item.disabled) return;
+      close();
+      item.onSelect?.();
+    });
+    return node;
+  });
+  menu.append(...buttons);
+  let closed = false;
+  const outside = (event) => { if (!menu.contains(event.target)) close({ restore: false }); };
+  function close({ restore = true } = {}) {
+    if (closed) return;
+    closed = true;
+    dom.doc.removeEventListener("pointerdown", outside, true);
+    menu.remove();
+    if (restore) returnFocus?.focus?.({ preventScroll: true });
+    onClose?.();
+  }
+  const enabled = () => buttons.filter((node) => node.getAttribute("aria-disabled") !== "true");
+  menu.addEventListener("keydown", (event) => {
+    const list = enabled();
+    const at = list.indexOf(dom.doc.activeElement);
+    const go = (index) => { event.preventDefault(); event.stopPropagation(); list[(index + list.length) % list.length]?.focus(); };
+    if (event.key === "ArrowDown") go(at + 1);
+    else if (event.key === "ArrowUp") go(at < 0 ? -1 : at - 1);
+    else if (event.key === "Home") go(0);
+    else if (event.key === "End") go(-1);
+    else if (event.key === "Escape") { event.preventDefault(); event.stopPropagation(); close(); }
+    else if (event.key === "Tab") close({ restore: false });
+    else if (event.key === "Enter" || event.key === " ") { event.preventDefault(); event.stopPropagation(); if (dom.doc.activeElement?.click) dom.doc.activeElement.click(); }
+  });
+  host.append(menu);
+  const bounds = host.getBoundingClientRect();
+  const width = menu.offsetWidth || 200, height = menu.offsetHeight || buttons.length * 32;
+  menu.style.left = `${Math.max(4, Math.min(x - bounds.left, bounds.width - width - 4))}px`;
+  menu.style.top = `${Math.max(4, Math.min(y - bounds.top, bounds.height - height - 4))}px`;
+  dom.doc.addEventListener("pointerdown", outside, true);
+  enabled()[0]?.focus();
+  return { element: menu, close };
+}

package/dist/studio-kit/drag.d.ts

@@ -0,0 +1,26 @@
+/** CE-18 studio kit (internal): the drag controller (threshold, touch hold, trial drop, Escape), pointer tracking and the drag label. */
+import type { KitDom } from "./dom.js";
+export interface KitPress<Payload> { x: number; y: number; id: number; type: string; time: number; payload: Payload }
+export interface KitDragOptions<Payload, Session> {
+  doc?: Document;
+  threshold?: number;
+  holdMs?: number;
+  now?(): number;
+  onStart?(press: KitPress<Payload>): Session | null | undefined;
+  onStarted?(session: Session): void;
+  onMove?(session: Session, event: PointerEvent): void;
+  onEnd?(session: Session, info: { cancelled: boolean }): void;
+  onDrop?(session: Session, event: PointerEvent): void;
+  onEscape?(session: Session): void;
+}
+export interface KitDragController<Payload, Session> {
+  readonly active: Session | null;
+  readonly pending: KitPress<Payload> | null;
+  press(event: PointerEvent, payload: Payload): void;
+  move(event: PointerEvent): boolean;
+  release(event: PointerEvent): boolean;
+  cancel(): boolean;
+}
+export declare function createDragController<Payload, Session>(options?: KitDragOptions<Payload, Session>): KitDragController<Payload, Session>;
+export declare function trackPointer(node: HTMLElement, options: { doc?: Document; onMove(event: PointerEvent): void; onEnd(commit: boolean): void }): { cancel(): void };
+export declare function dragGhost(dom: KitDom, host: HTMLElement, text: string): { element: HTMLElement; moveTo(event: { clientX: number; clientY: number }): void; remove(): void };

package/dist/studio-kit/drag.js

@@ -0,0 +1,127 @@
+// CE-18, the studio kit: dragging. `createDragController` turns a press into a drag once the pointer moves past a threshold (on touch, after a
+// hold, so a scroll is never taken for a move), runs the host's trial drop on each move, lands it once on release, and cancels on Escape.
+// `trackPointer` follows one captured pointer (a divider) until it is released or cancelled. `dragGhost` is the label that follows the
+// pointer. No document knowledge: the host decides what a drag carries and what a drop does.
+
+/**
+ * A drag controller. Options:
+ * - `doc`: the document (for the Escape key while dragging);
+ * - `threshold`: the distance in pixels before a press becomes a drag (default 4);
+ * - `holdMs`: on touch, how long the press must be held before movement drags (default 0); moving earlier abandons the press;
+ * - `onStart(pending)`: make the drag session from the press (`{ x, y, id, type, time, payload }`); null or undefined refuses it;
+ * - `onStarted(session)`: after the controller holds the session (paint the dragging state here);
+ * - `onMove(session, event)`: each move while dragging (the trial drop);
+ * - `onEnd(session, { cancelled })`: clean up, before `onDrop` or after a cancel;
+ * - `onDrop(session, event)`: the release (land the drop);
+ * - `onEscape(session)`: after Escape cancelled the drag.
+ * The host forwards its pointer events: `press(event, payload)`, `move(event)` (true while dragging), `release(event)` (true when it ended a
+ * drag) and `cancel()`.
+ */
+export function createDragController(options = {}) {
+  const threshold = options.threshold ?? 4;
+  const holdMs = options.holdMs ?? 0;
+  const now = options.now ?? (() => Date.now());
+  let pending = null;
+  let active = null;
+
+  const onKey = (event) => {
+    if (event.key !== "Escape" || !active) return;
+    event.preventDefault();
+    event.stopPropagation();
+    const session = active;
+    controller.cancel();
+    options.onEscape?.(session);
+  };
+  const listen = (on) => { if (options.doc) (on ? options.doc.addEventListener : options.doc.removeEventListener).call(options.doc, "keydown", onKey, true); };
+
+  function start() {
+    const session = options.onStart ? options.onStart(pending) : pending;
+    if (session === null || session === undefined) { pending = null; return false; }
+    active = session;
+    listen(true);
+    options.onStarted?.(session);
+    return true;
+  }
+  function end(cancelled) {
+    const session = active;
+    listen(false);
+    active = null;
+    pending = null;
+    options.onEnd?.(session, { cancelled });
+    return session;
+  }
+
+  const controller = {
+    get active() { return active; },
+    get pending() { return pending; },
+    /** A press that may become a drag; `payload` is what the drag would carry. */
+    press(event, payload) {
+      pending = { x: event.clientX, y: event.clientY, id: event.pointerId, type: event.pointerType, time: now(), payload };
+    },
+    /** A move: starts the drag past the threshold, then reports each move. Returns true while a drag runs. */
+    move(event) {
+      if (pending && !active && Math.hypot(event.clientX - pending.x, event.clientY - pending.y) > threshold) {
+        if (holdMs > 0 && pending.type === "touch" && now() - pending.time < holdMs) pending = null;
+        else start();
+      }
+      if (!active) return false;
+      options.onMove?.(active, event);
+      return true;
+    },
+    /** The release: lands the drag (`onEnd`, then `onDrop`) and returns true, or forgets the press and returns false. */
+    release(event) {
+      if (!active) { pending = null; return false; }
+      const session = end(false);
+      options.onDrop?.(session, event);
+      return true;
+    },
+    /** Drop the press, and the drag if one runs (`onEnd` with `cancelled`). */
+    cancel() {
+      if (!active) { pending = null; return false; }
+      end(true);
+      return true;
+    },
+  };
+  return controller;
+}
+
+/**
+ * Follow one captured pointer on `node` from a press: `onMove(event)` on each move, then `onEnd(commit)`, true on release and false on
+ * cancel or Escape. Returns `{ cancel }`.
+ */
+export function trackPointer(node, { doc, onMove, onEnd }) {
+  let done = false;
+  const finish = (commit) => {
+    if (done) return;
+    done = true;
+    node.removeEventListener("pointermove", onMove);
+    node.removeEventListener("pointerup", onUp);
+    node.removeEventListener("pointercancel", onCancel);
+    doc?.removeEventListener("keydown", onKey, true);
+    onEnd(commit);
+  };
+  const onUp = () => finish(true);
+  const onCancel = () => finish(false);
+  const onKey = (event) => { if (event.key === "Escape") { event.preventDefault(); event.stopPropagation(); finish(false); } };
+  node.addEventListener("pointermove", onMove);
+  node.addEventListener("pointerup", onUp);
+  node.addEventListener("pointercancel", onCancel);
+  doc?.addEventListener("keydown", onKey, true);
+  return { cancel: () => finish(false) };
+}
+
+/** The label that follows the pointer during a drag ("Text", "3 blocks"), inside `host` (a positioned element). */
+export function dragGhost(dom, host, text) {
+  const ghost = dom.el("div", `${dom.prefix}-ghost`, { "aria-hidden": "true", text });
+  host.append(ghost);
+  return {
+    element: ghost,
+    /** Put the label just below and right of the pointer. */
+    moveTo(event) {
+      const box = host.getBoundingClientRect();
+      ghost.style.left = `${event.clientX - box.left + 12}px`;
+      ghost.style.top = `${event.clientY - box.top + 12}px`;
+    },
+    remove() { ghost.remove(); },
+  };
+}

package/dist/studio-kit/gesture.d.ts

@@ -0,0 +1,29 @@
+/** CE-18 studio kit (internal): gesture history (drafts while a gesture runs, one step at its end) and a snapshot history. */
+export interface KitGestureAdapter<Snapshot, Draft> {
+  snapshot(): Snapshot;
+  preview(draft: Draft, message?: string): void;
+  commit(start: Snapshot, info: { label: string; message: string }): boolean;
+  restore(start: Snapshot): void;
+}
+export interface KitGesture<Draft> {
+  readonly active: boolean;
+  readonly label: string | null;
+  begin(label: string): boolean;
+  update(draft: Draft, message?: string): boolean;
+  end(message?: string): boolean;
+  cancel(): boolean;
+  reset(): void;
+}
+export declare function createGesture<Snapshot, Draft>(adapter: KitGestureAdapter<Snapshot, Draft>): KitGesture<Draft>;
+export interface KitHistory<Snapshot extends object> {
+  readonly index: number;
+  readonly size: number;
+  readonly head: (Snapshot & { coalesce?: string | null; time?: number }) | undefined;
+  reset(snapshot: Snapshot): void;
+  push(snapshot: Snapshot, coalesce?: string | null): void;
+  append(snapshot: Snapshot): void;
+  canUndo(): boolean;
+  canRedo(): boolean;
+  go(step: number): (Snapshot & { coalesce?: string | null; time?: number }) | null;
+}
+export declare function createHistory<Snapshot extends object>(options?: { limit?: number; coalesceMs?: number; now?(): number }): KitHistory<Snapshot>;

package/dist/studio-kit/gesture.js

@@ -0,0 +1,87 @@
+// CE-18, the studio kit: gesture history. A gesture (a divider drag, a scrub) shows drafts while it runs and lands as one history step;
+// `createGesture` is that begin / update / end / cancel cycle over an adapter. `createHistory` is the snapshot history with coalescing that an
+// adapter without an editor session keeps (Layout Studio's record); a slide adapter uses the session's history instead. No DOM.
+
+/**
+ * A gesture over `adapter`:
+ * - `snapshot()`: the state to return to on cancel (taken at `begin`);
+ * - `preview(draft, message)`: show a draft (no history, no change callbacks);
+ * - `commit(start, { label, message })`: land the gesture as one step; returns whether anything changed;
+ * - `restore(start)`: put the state taken at `begin` back.
+ */
+export function createGesture(adapter) {
+  let active = null;
+  return {
+    get active() { return active !== null; },
+    get label() { return active?.label ?? null; },
+    /** Start a gesture; false while one is running. */
+    begin(label) {
+      if (active) return false;
+      active = { label, start: adapter.snapshot() };
+      return true;
+    },
+    /** Show a draft; false when no gesture runs. */
+    update(draft, message) {
+      if (!active) return false;
+      adapter.preview(draft, message);
+      return true;
+    },
+    /** Land the gesture as one step (`message`, else the label). Returns what `commit` returned, false when no gesture ran. */
+    end(message) {
+      if (!active) return false;
+      const { start, label } = active;
+      active = null;
+      return Boolean(adapter.commit(start, { label, message: message ?? label }));
+    },
+    /** Drop the gesture and restore the state from its start. */
+    cancel() {
+      if (!active) return false;
+      const { start } = active;
+      active = null;
+      adapter.restore(start);
+      return true;
+    },
+    /** Forget a running gesture without restoring anything (the document was replaced under it). */
+    reset() { active = null; },
+  };
+}
+
+/**
+ * A snapshot history: `reset(snapshot)` starts it, `push(snapshot, coalesce)` adds a step (a step with the same `coalesce` key within
+ * `coalesceMs` of the head replaces it, so typing in a field is one step), `append(snapshot)` adds one after the current step without the
+ * limit, and `go(-1 | 1)` moves and returns the step (null past either end). At most `limit` steps are kept; the oldest are dropped.
+ */
+export function createHistory({ limit = 200, coalesceMs = 1500, now = () => Date.now() } = {}) {
+  let entries = [];
+  let index = 0;
+  return {
+    get index() { return index; },
+    get size() { return entries.length; },
+    get head() { return entries[index]; },
+    reset(snapshot) { entries = [{ ...snapshot }]; index = 0; },
+    push(snapshot, coalesce) {
+      const head = entries[index];
+      const time = now();
+      if (coalesce && head?.coalesce === coalesce && time - head.time < coalesceMs && index === entries.length - 1 && index > 0) {
+        entries[index] = { ...snapshot, coalesce, time };
+        return;
+      }
+      entries.length = index + 1;
+      entries.push({ ...snapshot, coalesce, time });
+      if (entries.length > limit) entries.shift(); else index++;
+    },
+    append(snapshot) {
+      entries.length = index + 1;
+      entries.push({ ...snapshot, time: now() });
+      index++;
+    },
+    canUndo: () => index > 0,
+    canRedo: () => index < entries.length - 1,
+    go(step) {
+      const target = index + step;
+      if (target < 0 || target >= entries.length) return null;
+      index = target;
+      return entries[target];
+    },
+  };
+}

package/dist/studio-kit/index.d.ts

@@ -0,0 +1,29 @@
+/** CE-18: the studio kit (internal; no package subpath exports it yet). The document adapter a studio supplies is `StudioDocumentAdapter`. */
+export * from "./dom.js";
+export * from "./commands.js";
+export * from "./selection.js";
+export * from "./gesture.js";
+export * from "./viewport.js";
+export * from "./overlay.js";
+export * from "./drag.js";
+export * from "./tree.js";
+export * from "./inspector.js";
+import type { KitBox } from "./overlay.js";
+
+/** One node of a studio document, as the layers, the overlay and the screen reader see it. */
+export interface StudioNode<Key = string> { key: string; path: Key; kind: string; parent: string | null; depth: number; label: string; findings: { message: string }[] }
+/** What a studio needs from a document (Layout Studio: src/layout-adapter.js; the slide adapter is CE-19). */
+export interface StudioDocumentAdapter<Key, Draft = unknown> {
+  nodes(): StudioNode<Key>[];
+  boxOf(key: Key): (KitBox & { depth: number }) | undefined;
+  containerOf(key: Key): { direction: "row" | "column"; tracks: { start: number; length: number }[] } | undefined;
+  hitChain(point: { x: number; y: number }, skip?: (box: KitBox) => boolean): (KitBox & { depth: number })[];
+  trialMove(keys: Key[], target: Key, index: number): { ok: boolean; reason: string; noop: boolean };
+  run(command: string, ...args: unknown[]): boolean;
+  begin(label: string): boolean;
+  preview(draft: Draft, message?: string): void;
+  commit(message?: string): boolean;
+  cancel(): void;
+  undo(): boolean;
+  redo(): boolean;
+}

package/dist/studio-kit/index.js

@@ -0,0 +1,12 @@
+// CE-18: the studio kit, the parts Layout Studio and the Studio share (STUDY.md 3.6, STUDIO-SPEC.md 17). It is internal for now: no package
+// subpath exports it until a second studio uses it (then `@openpresentation/opf-editor/studio-kit`). Nothing here knows a document format;
+// a studio supplies a document adapter (src/layout-adapter.js for Layout Studio).
+export { ICONS, KIT_PREFIX, createDom, isMac, isTypingTarget, nextId, openMenu, pct } from "./dom.js";
+export { createCommandRegistry, formatKey, isHandled, keyGuard, markHandled, matchKey, parseKey } from "./commands.js";
+export { clickTarget, createSelection } from "./selection.js";
+export { createGesture, createHistory } from "./gesture.js";
+export { ZOOM_STEPS, clampZoom, createViewport, scrollForZoom, stepZoom, toUnit } from "./viewport.js";
+export { boxesAt, createKeyedLayer, createOverlay, dividerKeyAction, inside, paintBadge, paintDivider, paintSelectable, ratioLabel, setBox } from "./overlay.js";
+export { createDragController, dragGhost, trackPointer } from "./drag.js";
+export { hitRow, rovingTabStop, rowDropMode, showTreeDrop, treeItem, treeKeyAction } from "./tree.js";
+export { createFields, createInspectorFrame } from "./inspector.js";

package/dist/studio-kit/inspector.d.ts

@@ -0,0 +1,22 @@
+/** CE-18 studio kit (internal): the inspector frame (sections chosen by the selection) and its field builders. */
+import type { KitDom } from "./dom.js";
+export interface KitInspectorSection<Ctx> { id: string; when?(ctx: Ctx): boolean; render(body: HTMLElement, ctx: Ctx): void }
+export interface KitInspectorFrame<Ctx> {
+  readonly editing: boolean;
+  sectionsFor(ctx: Ctx): KitInspectorSection<Ctx>[];
+  register(section: KitInspectorSection<Ctx>, options?: { before?: string }): () => void;
+  render(): void;
+  update(): void;
+  check(fn: () => void): void;
+  edit(callback: () => void): void;
+}
+export declare function createInspectorFrame<Ctx>(body: HTMLElement, options?: { sections?: KitInspectorSection<Ctx>[]; context?(): Ctx; before?(ctx: Ctx): void; after?(ctx: Ctx): void }): KitInspectorFrame<Ctx>;
+export interface KitFields<Path> {
+  field(label: string, control: HTMLElement, options?: { help?: string; path?: Path; field?: string; labelFor?: string; group?: boolean; target?: HTMLElement }): HTMLElement & { error: HTMLElement };
+  textInput(value: string | undefined, options?: { onInput?(value: string): void; name?: string; pattern?: string; placeholder?: string; multiline?: boolean }): HTMLInputElement | HTMLTextAreaElement;
+  select(entries: [string, string][], current: string, options: { onChange(value: string): void; name: string }): HTMLSelectElement;
+  segmented(entries: [string, string, string?][], current: string, options: { onPick(value: string): void; label: string; name: string }): HTMLElement;
+  actionButton(text: string, iconName: string | undefined, run: () => void, options?: { label?: string; disabled?: boolean; shortcut?: string }): HTMLButtonElement;
+  section(label?: string): HTMLElement;
+}
+export declare function createFields<Path>(dom: KitDom, frame: KitInspectorFrame<unknown>, options?: { idPrefix?: string; issues?(path: Path, field: string): { message: string }[]; readOnly?(): boolean }): KitFields<Path>;

package/dist/studio-kit/inspector.js

@@ -0,0 +1,119 @@
+// CE-18, the studio kit: the inspector frame. Sections are registered with `when(ctx)` and `render(body, ctx)`; every section whose `when`
+// holds for the current selection is drawn, in order. While the person types in a field of the panel, a change only refreshes the findings
+// under the fields (`update`), so the field keeps its focus and caret; any other change redraws the panel and puts focus back on the same
+// field. `createFields` builds the labeled fields, with core's findings shown under each. Plain DOM, styled by class prefix.
+import { nextId } from "./dom.js";
+
+/**
+ * The frame over `body`. Options: `sections` (`{ id, when(ctx), render(body, ctx) }`, in order), `context()` (the ctx of a redraw),
+ * `before(ctx)` and `after(ctx)` (around the sections: a title, findings that fit no field). Returns `{ render, update, edit, check, editing,
+ * sections }`: `edit(callback)` runs an edit from a typed field, `check(fn)` adds a findings check that `update` runs.
+ */
+export function createInspectorFrame(body, { sections = [], context = () => ({}), before, after } = {}) {
+  const list = [...sections];
+  let checks = [];
+  let editing = false;
+  const frame = {
+    get editing() { return editing; },
+    /** The sections drawn for `ctx`, in order. */
+    sectionsFor: (ctx) => list.filter((section) => section.when ? section.when(ctx) === true : true),
+    /** Add a section (before the one with id `before`, else at the end). Returns the function that removes it. */
+    register(section, { before: id } = {}) {
+      const at = id ? list.findIndex((entry) => entry.id === id) : -1;
+      if (at >= 0) list.splice(at, 0, section); else list.push(section);
+      return () => { const index = list.indexOf(section); if (index >= 0) list.splice(index, 1); };
+    },
+    render() {
+      const doc = body.ownerDocument;
+      const active = doc.activeElement;
+      const focusKey = body.contains(active) ? active.dataset?.field : undefined;
+      checks = [];
+      body.replaceChildren();
+      const ctx = context();
+      before?.(ctx);
+      for (const section of frame.sectionsFor(ctx)) section.render(body, ctx);
+      after?.(ctx);
+      frame.update();
+      if (focusKey) body.querySelector(`[data-field="${focusKey}"]`)?.focus({ preventScroll: true });
+    },
+    update() { for (const check of checks) check(); },
+    check(fn) { checks.push(fn); },
+    edit(callback) { editing = true; try { callback(); } finally { editing = false; } },
+  };
+  return frame;
+}
+
+/**
+ * Field builders bound to a frame. Options: `idPrefix` (field ids), `issues(path, field)` (the findings of one field, `{ message }`),
+ * `readOnly()`. Each builder returns an element; `field` wraps a control with its label, help and the live findings line.
+ */
+export function createFields(dom, frame, { idPrefix = nextId(`${dom.prefix}-fields`), issues = () => [], readOnly = () => false } = {}) {
+  const { el } = dom;
+  const p = dom.prefix;
+  /** A labeled field. `path`/`field` tie it to the findings: they show under the field and mark it invalid. */
+  function field(label, control, { help, path, field: key, labelFor, group, target } = {}) {
+    const wrap = el("div", `${p}-field`, { "data-field-name": key ?? "" });
+    const fieldId = `${idPrefix}-${nextId("f")}`;
+    const focusTarget = target ?? control;
+    if (group) {
+      const caption = el("span", `${p}-label-text`, { id: `${fieldId}-label`, text: label });
+      control.setAttribute("aria-labelledby", `${fieldId}-label`);
+      if (!control.getAttribute("role")) control.setAttribute("role", "group");
+      wrap.append(caption);
+    } else {
+      if (!labelFor && !control.id) control.id = fieldId;
+      wrap.append(el("label", `${p}-label-text`, { for: labelFor ?? control.id, text: label }));
+    }
+    wrap.append(control);
+    if (help) { const note = el("p", `${p}-help`, { id: `${fieldId}-help`, text: help }); wrap.append(note); if (!group) focusTarget.setAttribute("aria-describedby", note.id); }
+    const error = el("p", `${p}-field-error`, { id: `${fieldId}-error`, role: "status", "aria-live": "polite" });
+    error.hidden = true;
+    wrap.append(error);
+    if (path && key) {
+      frame.check(() => {
+        const found = issues(path, key);
+        error.hidden = !found.length;
+        error.replaceChildren();
+        if (found.length) error.append(dom.icon("CircleX", 14), el("span", "", { text: found.map((issue) => issue.message).join(" ") }));
+        wrap.dataset.invalid = String(Boolean(found.length));
+        if (!group) { if (found.length) { focusTarget.setAttribute("aria-invalid", "true"); focusTarget.setAttribute("aria-errormessage", error.id); } else { focusTarget.removeAttribute("aria-invalid"); focusTarget.removeAttribute("aria-errormessage"); } }
+      });
+    }
+    return Object.assign(wrap, { error });
+  }
+  /** A text field (or a textarea, `multiline`); `onInput(value)` runs as a typed edit. */
+  function textInput(value, { onInput, name, pattern, placeholder, multiline } = {}) {
+    const input = el(multiline ? "textarea" : "input", `${p}-input`, { type: multiline ? undefined : "text", "data-field": name, pattern, placeholder, spellcheck: "false", autocomplete: "off", rows: multiline ? 2 : undefined });
+    input.value = value ?? "";
+    input.addEventListener("input", () => frame.edit(() => onInput(input.value)));
+    return input;
+  }
+  /** A select of `[value, label]` entries. */
+  function select(entries, current, { onChange, name }) {
+    const input = el("select", `${p}-select`, { "data-field": name });
+    for (const [value, label] of entries) { const option = el("option", "", { value, text: label }); input.append(option); }
+    input.value = current;
+    input.addEventListener("change", () => onChange(input.value));
+    return input;
+  }
+  /** A segmented control of `[value, text, iconName]` entries (toggle buttons, one pressed). */
+  function segmented(entries, current, { onPick, label, name }) {
+    const wrap = el("div", `${p}-segmented`, { role: "group", "aria-label": label });
+    for (const [value, text, iconName] of entries) {
+      const button = dom.button(`${p}-segment`, { text, iconName, size: 14, pressed: value === current, attributes: { "data-field": `${name}-${value}`, "data-value": value } });
+      button.addEventListener("click", () => { if (value !== current) onPick(value); });
+      wrap.append(button);
+    }
+    return wrap;
+  }
+  /** An action button, disabled when `disabled` or read only. */
+  const actionButton = (text, iconName, run, { label, disabled, shortcut } = {}) => {
+    const button = dom.button(`${p}-action`, { text, iconName, size: 14, attributes: { "aria-label": label, "aria-keyshortcuts": shortcut } });
+    button.disabled = Boolean(disabled) || readOnly();
+    button.addEventListener("click", () => run());
+    return button;
+  };
+  /** A section of the panel, with an optional title. */
+  const section = (label) => { const node = el("div", `${p}-section`); if (label) node.append(el("h3", `${p}-section-title`, { text: label })); return node; };
+  return { field, textInput, select, segmented, actionButton, section };
+}