@openpresentation/opf-editor 0.27.0 → 0.29.0

package/dist/studio-kit/tree.js

@@ -0,0 +1,82 @@
+// CE-18, the studio kit: the layers tree (the WAI-ARIA tree pattern). `treeItem` makes a `role="treeitem"` with its level, place, selection
+// and expansion; `rovingTabStop` keeps one item in the tab order; `treeKeyAction` says what a key does on a focused item; `rowDropMode` and
+// `hitRow` find where a dragged row would land; `showTreeDrop` draws that place. The host builds the rows and owns the document.
+
+/**
+ * A tree item (`li`, `role="treeitem"`). `expanded` is true or false for an item with children and undefined for a leaf; `setsize` and
+ * `posinset` (1-based) are left out for the root. `attributes` are added as they are (`data-*`).
+ */
+export function treeItem(dom, { level, selected, expanded, setsize, posinset, attributes = {}, className = `${dom.prefix}-item` }) {
+  const li = dom.el("li", className, { role: "treeitem", "aria-level": level, ...attributes });
+  li.setAttribute("aria-selected", String(Boolean(selected)));
+  if (expanded !== undefined) li.setAttribute("aria-expanded", String(Boolean(expanded)));
+  if (setsize !== undefined) { li.setAttribute("aria-setsize", String(setsize)); li.setAttribute("aria-posinset", String(posinset)); }
+  return li;
+}
+
+/** Make `stop` the one item of `items` in the tab order. */
+export function rovingTabStop(items, stop) {
+  for (const item of items) item.tabIndex = item === stop ? 0 : -1;
+}
+
+/**
+ * What a key does on the focused tree item `item` (the tree pattern). `items` are the visible items in order. Returns null, or:
+ * - `{ type: "focus", target }` (ArrowDown, ArrowUp, Home, End; ArrowRight on an expanded item goes to `firstChild`, ArrowLeft on a child to
+ *   `parent`; `target` may be null when there is nowhere to go, and the key is still the tree's);
+ * - `{ type: "expand" }` (ArrowRight on a collapsed item) and `{ type: "collapse" }` (ArrowLeft on an expanded item that can collapse);
+ * - `{ type: "activate" }` (Enter or Space) and `{ type: "menu" }` (the ContextMenu key or Shift+F10, on an item that has one).
+ * `state` is `{ expandable, expanded, collapsible, parent, firstChild, menu }`.
+ */
+export function treeKeyAction(event, item, items, state = {}) {
+  const at = items.indexOf(item);
+  const focus = (target) => ({ type: "focus", target: target ?? null });
+  switch (event.key) {
+    case "ArrowDown": return focus(items[Math.min(items.length - 1, at + 1)]);
+    case "ArrowUp": return focus(items[Math.max(0, at - 1)]);
+    case "Home": return focus(items[0]);
+    case "End": return focus(items[items.length - 1]);
+    case "ArrowRight":
+      if (!state.expandable) return null;
+      return state.expanded ? focus(state.firstChild) : { type: "expand" };
+    case "ArrowLeft":
+      if (state.expanded && state.collapsible) return { type: "collapse" };
+      return state.parent ? focus(state.parent) : null;
+    case "Enter":
+    case " ":
+      return { type: "activate" };
+    default:
+      if ((event.key === "ContextMenu" || (event.key === "F10" && event.shiftKey)) && state.menu) return { type: "menu" };
+      return null;
+  }
+}
+
+/** The row of `rows` (`{ row, ... }`, `row` an element) that a client y is over, or undefined. */
+export const hitRow = (rows, clientY) => rows.find(({ row }) => { const box = row.getBoundingClientRect(); return clientY >= box.top && clientY <= box.bottom; });
+
+/**
+ * Where a drop at `fraction` of a row's height lands: "into" the row (always for the root, and in the middle 40% of a container), else
+ * "before" (the upper half) or "after".
+ */
+export function rowDropMode(fraction, { root = false, container = false } = {}) {
+  if (root) return "into";
+  if (container && fraction >= 0.3 && fraction <= 0.7) return "into";
+  return fraction < 0.5 ? "before" : "after";
+}
+
+/**
+ * Draw the drop place on `mark` (positioned in `scroller`): a line above or below the row's box, or the whole box for "into". `state` is
+ * "ok", "same" or "refused", with `reason` as its title. A null drop hides it.
+ */
+export function showTreeDrop(mark, scroller, drop) {
+  if (!drop) { mark.hidden = true; return; }
+  const parent = scroller.getBoundingClientRect();
+  mark.hidden = false;
+  mark.dataset.mode = drop.mode;
+  mark.dataset.state = drop.state;
+  mark.title = drop.reason ?? "";
+  const top = drop.mode === "after" ? drop.box.bottom : drop.box.top;
+  mark.style.top = `${top - parent.top + scroller.scrollTop}px`;
+  mark.style.left = `${drop.box.left - parent.left}px`;
+  mark.style.width = `${drop.box.width}px`;
+  mark.style.height = drop.mode === "into" ? `${drop.box.height}px` : "0px";
+}

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

@@ -0,0 +1,29 @@
+/** CE-18 studio kit (internal): zoom (steps, smooth, fit), pan (hand, Space, two fingers) and screen-to-unit mapping. */
+export declare const ZOOM_STEPS: readonly number[];
+export declare function clampZoom(value: number, steps?: readonly number[]): number;
+export declare function stepZoom(zoom: number, direction: number, steps?: readonly number[]): number;
+export declare function toUnit(point: { clientX: number; clientY: number }, rect: { left: number; top: number; width: number; height: number }): { x: number; y: number };
+export declare function scrollForZoom(scroll: { left: number; top: number }, anchor: { x: number; y: number }, from: number, to: number): { left: number; top: number };
+export interface KitViewportOptions {
+  root?: HTMLElement;
+  zoomVar?: string;
+  steps?: readonly number[];
+  zoom?: number;
+  panEnabled?(): boolean;
+  wheel?: "step" | "smooth" | false;
+  pinch?: boolean;
+  fitZoom?(mode: "slide" | "width"): number;
+  onZoom?(zoom: number): void;
+}
+export interface KitViewport {
+  readonly zoom: number;
+  readonly panMode: boolean;
+  readonly panning: boolean;
+  setZoom(zoom: number, options?: { anchor?: { clientX: number; clientY: number } }): number;
+  step(direction: number, options?: { anchor?: { clientX: number; clientY: number } }): number;
+  fit(mode?: "slide" | "width"): number;
+  holdSpace(on: boolean): void;
+  toUnit(event: { clientX: number; clientY: number }, element: Element): { x: number; y: number };
+  destroy(): void;
+}
+export declare function createViewport(viewport: HTMLElement, options?: KitViewportOptions): KitViewport;

package/dist/studio-kit/viewport.js

@@ -0,0 +1,153 @@
+// CE-18, the studio kit: the viewport around a studio's frame. Zoom in steps (buttons, keys, Ctrl or Cmd with the wheel), smooth zoom (a
+// trackpad pinch, two-finger touch), fit, and pan (the hand tool, a held Space, two fingers), plus the mapping from screen points to the
+// frame's unit square. The zoom is a factor of the fitted size, written to a CSS variable on the root; the stylesheet sizes the stage from it.
+
+/** The zoom steps of the Studio (STUDIO-SPEC 4.2), as factors of the fitted size. */
+export const ZOOM_STEPS = Object.freeze([0.25, 0.5, 0.75, 1, 1.5, 2, 3, 4]);
+
+/** `value` kept between the first and the last step. */
+export const clampZoom = (value, steps = ZOOM_STEPS) => Math.max(steps[0], Math.min(steps[steps.length - 1], value));
+
+/** The next step up (`direction` 1) or down (-1) from `zoom`; a zoom between two steps goes to the nearer one in that direction. */
+export function stepZoom(zoom, direction, steps = ZOOM_STEPS) {
+  const at = steps.findIndex((value) => value >= zoom - 1e-9);
+  const index = direction > 0 ? (steps[at] > zoom + 1e-9 ? at : at + 1) : at - 1;
+  return steps[Math.max(0, Math.min(steps.length - 1, index))];
+}
+
+/** A client point as a fraction of `rect` (a DOMRect): `{ x, y }`, 0 to 1 inside it. */
+export const toUnit = (point, rect) => ({ x: (point.clientX - rect.left) / (rect.width || 1), y: (point.clientY - rect.top) / (rect.height || 1) });
+
+/**
+ * The scroll position that keeps the content point under `anchor` (client coordinates, relative to the viewport's box) in place when the
+ * zoom changes from `from` to `to`: `{ left, top }`.
+ */
+export function scrollForZoom({ left, top }, anchor, from, to) {
+  const ratio = to / (from || 1);
+  return { left: (left + anchor.x) * ratio - anchor.x, top: (top + anchor.y) * ratio - anchor.y };
+}
+
+/**
+ * Attach zoom and pan to `viewport` (the scrolling element). Options:
+ * - `root`: where the zoom variable and the `data-zoomed`, `data-panning` and `data-space` states go (default the viewport);
+ * - `zoomVar`: the CSS variable (default `--opf-kit-zoom`); `steps` (default `ZOOM_STEPS`); `zoom` (the first zoom, default 1);
+ * - `panEnabled()`: whether a drag pans now (the hand tool); a held Space pans as well (`holdSpace`);
+ * - `wheel`: "step" (Ctrl or Cmd with the wheel steps the zoom, the default), "smooth" (it zooms continuously around the pointer) or false;
+ * - `pinch`: two touch pointers zoom around their midpoint and pan (default false);
+ * - `fitZoom(mode)`: the zoom of `fit(mode)` ("slide" or "width"), default 1 (the zoom is a factor of the fitted size);
+ * - `onZoom(zoom)`: after each change.
+ * Returns `{ zoom, panMode, setZoom, step, fit, holdSpace, toUnit, destroy }`.
+ */
+export function createViewport(viewport, options = {}) {
+  const root = options.root ?? viewport;
+  const steps = options.steps ?? ZOOM_STEPS;
+  const zoomVar = options.zoomVar ?? "--opf-kit-zoom";
+  const wheelMode = options.wheel === undefined ? "step" : options.wheel;
+  let zoom = 1;
+  let spaceHeld = false;
+  let pan = null;
+  const touches = new Map();
+  let pinch = null;
+  const panMode = () => Boolean(options.panEnabled?.()) || spaceHeld;
+
+  function setZoom(value, { anchor } = {}) {
+    const next = clampZoom(value, steps);
+    const before = zoom;
+    zoom = next;
+    root.style.setProperty(zoomVar, String(zoom));
+    root.dataset.zoomed = String(zoom !== 1);
+    if (anchor && before !== next) {
+      const box = viewport.getBoundingClientRect();
+      const scroll = scrollForZoom({ left: viewport.scrollLeft, top: viewport.scrollTop }, { x: anchor.clientX - box.left, y: anchor.clientY - box.top }, before, next);
+      viewport.scrollLeft = scroll.left;
+      viewport.scrollTop = scroll.top;
+    }
+    options.onZoom?.(zoom);
+    return zoom;
+  }
+  const step = (direction, opts) => setZoom(stepZoom(zoom, direction, steps), opts);
+  const fit = (mode = "slide") => setZoom(options.fitZoom ? options.fitZoom(mode) : 1);
+
+  // Pan: a drag with the hand tool or Space; the capture phase keeps the drag from reaching the frame below.
+  const onDown = (event) => {
+    if (options.pinch && event.pointerType === "touch") {
+      touches.set(event.pointerId, { x: event.clientX, y: event.clientY });
+      if (touches.size === 2) { startPinch(); event.preventDefault(); event.stopPropagation(); return; }
+    }
+    if (!panMode() || (event.pointerType === "mouse" && event.button !== 0)) return;
+    event.preventDefault();
+    event.stopPropagation();
+    pan = { x: event.clientX, y: event.clientY, left: viewport.scrollLeft, top: viewport.scrollTop };
+    root.dataset.panning = "true";
+    viewport.setPointerCapture?.(event.pointerId);
+  };
+  const onMove = (event) => {
+    if (touches.has(event.pointerId)) {
+      touches.set(event.pointerId, { x: event.clientX, y: event.clientY });
+      if (pinch) { movePinch(); return; }
+    }
+    if (!pan) return;
+    viewport.scrollLeft = pan.left - (event.clientX - pan.x);
+    viewport.scrollTop = pan.top - (event.clientY - pan.y);
+  };
+  const endPan = (event) => {
+    if (event && touches.delete(event.pointerId) && pinch && touches.size < 2) { pinch = null; delete root.dataset.panning; }
+    pan = null;
+    delete root.dataset.panning;
+  };
+
+  // Two fingers: the distance between them scales the zoom from where it was, and the content point first under their midpoint stays
+  // under it (so moving both fingers pans).
+  const pair = () => { const [a, b] = [...touches.values()]; return { distance: Math.hypot(b.x - a.x, b.y - a.y) || 1, mid: { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 } }; };
+  function startPinch() {
+    pan = null;
+    const { distance, mid } = pair();
+    const box = viewport.getBoundingClientRect();
+    pinch = { distance, zoom, point: { x: (viewport.scrollLeft + mid.x - box.left) / zoom, y: (viewport.scrollTop + mid.y - box.top) / zoom } };
+    root.dataset.panning = "true";
+  }
+  function movePinch() {
+    const { distance, mid } = pair();
+    const next = setZoom(pinch.zoom * (distance / pinch.distance));
+    const box = viewport.getBoundingClientRect();
+    viewport.scrollLeft = pinch.point.x * next - (mid.x - box.left);
+    viewport.scrollTop = pinch.point.y * next - (mid.y - box.top);
+  }
+
+  const onWheel = (event) => {
+    if (!wheelMode || !(event.ctrlKey || event.metaKey)) return;
+    event.preventDefault();
+    if (wheelMode === "smooth") setZoom(zoom * Math.exp(-event.deltaY * 0.01), { anchor: event });
+    else step(event.deltaY < 0 ? 1 : -1);
+  };
+
+  viewport.addEventListener("pointerdown", onDown, true);
+  viewport.addEventListener("pointermove", onMove);
+  viewport.addEventListener("pointerup", endPan);
+  viewport.addEventListener("pointercancel", endPan);
+  viewport.addEventListener("wheel", onWheel, { passive: false });
+  setZoom(options.zoom ?? 1);
+
+  return {
+    get zoom() { return zoom; },
+    get panMode() { return panMode(); },
+    get panning() { return pan !== null || pinch !== null; },
+    setZoom,
+    step,
+    fit,
+    /** Space held (true) or released (false): a drag pans while it is held. */
+    holdSpace(on) {
+      spaceHeld = Boolean(on);
+      if (spaceHeld) root.dataset.space = "true"; else delete root.dataset.space;
+    },
+    /** A pointer event's position as a fraction of `element`'s box. */
+    toUnit: (event, element) => toUnit(event, element.getBoundingClientRect()),
+    destroy() {
+      viewport.removeEventListener("pointerdown", onDown, true);
+      viewport.removeEventListener("pointermove", onMove);
+      viewport.removeEventListener("pointerup", endPan);
+      viewport.removeEventListener("pointercancel", endPan);
+      viewport.removeEventListener("wheel", onWheel);
+    },
+  };
+}

package/dist/studio-layers.d.ts

@@ -0,0 +1,12 @@
+/** CE-20 (internal): the Studio's layers tree over the current slide's scene. */
+import type { KitDom } from "./studio-kit/dom.js";
+import type { SlideAdapter } from "./slide-adapter.js";
+
+export interface StudioLayers {
+  element: HTMLElement;
+  render(): void;
+  paintSelection(options?: { focus?: boolean }): void;
+  focus(): void;
+  destroy(): void;
+}
+export declare function createStudioLayers(container: HTMLElement, options: { dom: KitDom; adapter: SlideAdapter; studio: any }): StudioLayers;

package/dist/studio-layers.js

@@ -0,0 +1,218 @@
+// CE-20: the Studio's layers panel, the current slide's scene as a tree (the WAI-ARIA tree pattern from the kit: `role="tree"`, a roving tab
+// stop, `aria-level`, `aria-setsize`, `aria-posinset`, `aria-selected`, `aria-expanded`). A click selects, Shift+click selects a range of
+// siblings, Cmd or Ctrl+click toggles one; the arrow keys move and expand or collapse; Enter goes to the canvas with that node selected; F2 edits
+// a text node; a drag reorders or moves into a container with the canvas's trial and reason. One selection for every surface: the Studio
+// owns it, this only draws it and asks for changes.
+import { hitRow, rovingTabStop, rowDropMode, showTreeDrop, treeItem, treeKeyAction } from "./studio-kit/tree.js";
+import { isTypingTarget } from "./studio-kit/dom.js";
+
+const ICON_OF = { slide: "Square", heading: "Heading", region: "Columns2", group: "Group", implicit: "AlignLeft", part: "GitCommitHorizontal" };
+const TYPE_ICON = { text: "AlignLeft", list: "List", image: "Image", video: "Video", chart: "ChartColumn", table: "Table", code: "Code", metric: "Hash", quote: "Quote", timeline: "CalendarRange" };
+
+/**
+ * Mount the layers tree in `container`. `adapter` is the slide adapter, `studio` the controller. Returns `{ element, render, paintSelection,
+ * focus, destroy }`.
+ */
+export function createStudioLayers(container, { dom, adapter, studio }) {
+  const doc = container.ownerDocument;
+  const { el } = dom;
+  const p = dom.prefix;
+  const scroller = el("div", `${p}-layers-scroll`);
+  const tree = el("ul", `${p}-tree`, { role: "tree", "aria-label": "Layers", "aria-multiselectable": "true" });
+  const mark = el("div", `${p}-tree-drop`, { "aria-hidden": "true" });
+  mark.hidden = true;
+  scroller.append(tree, mark);
+  container.append(scroller);
+  const collapsed = new Set();
+  let rows = [];
+  let focusKey = null;
+  let drag = null;
+  let lastScene = null;
+
+  const scene = () => adapter.scene();
+  const visibleChildren = (s, key) => s.children(key).filter((node) => node.kind !== "part");
+
+  function render() {
+    const s = scene();
+    lastScene = s;
+    const hadFocus = tree.contains(doc.activeElement);
+    const selected = new Set(studio.selectedKeys());
+    const items = [];
+    rows = [];
+    const add = (node, level, setsize, posinset) => {
+      const children = visibleChildren(s, node.key);
+      const expandable = children.length > 0;
+      const expanded = expandable && !collapsed.has(node.key);
+      const li = treeItem(dom, { level, selected: selected.has(node.key), expanded: expandable ? expanded : undefined, setsize: level > 1 ? setsize : undefined, posinset: level > 1 ? posinset : undefined, attributes: { "data-key": node.key, "data-kind": node.kind }, className: `${p}-row` });
+      const label = el("span", `${p}-row-label`);
+      label.style.setProperty("--opf-studio-level", String(level - 1));
+      if (expandable) {
+        const caret = el("span", `${p}-caret`, { "aria-hidden": "true" });
+        caret.append(dom.icon(expanded ? "ChevronDown" : "ChevronRight", 14));
+        caret.addEventListener("click", (event) => { event.stopPropagation(); toggle(node.key); });
+        label.append(caret);
+      } else label.append(el("span", `${p}-caret`, { "aria-hidden": "true" }));
+      label.append(dom.icon(node.kind === "block" || node.kind === "implicit" ? TYPE_ICON[node.type] ?? "Square" : ICON_OF[node.kind] ?? "Square", 14));
+      label.append(el("span", `${p}-row-text`, { text: node.kind === "slide" ? studio.slideLabel(node) : node.label }));
+      if (node.findings.length) label.append(el("span", `${p}-row-badge`, { text: String(node.findings.length), title: node.findings.map((finding) => finding.message).join("\n"), "aria-label": `${node.findings.length} finding${node.findings.length === 1 ? "" : "s"}` }));
+      if (node.hidden) { const hidden = el("span", `${p}-row-hidden`, { title: "Hidden slide" }); hidden.append(dom.icon("EyeOff", 14)); label.append(hidden); }
+      li.append(label);
+      items.push(li);
+      rows.push({ row: li, key: node.key, node, level, expandable, expanded });
+      if (expanded) {
+        const group = el("ul", `${p}-tree-group`, { role: "group" });
+        li.append(group);
+        const parentItems = items.length;
+        children.forEach((child, index) => add(child, level + 1, children.length, index + 1));
+        group.append(...items.splice(parentItems));
+      }
+    };
+    const slide = s.node(s.slideKey);
+    add(slide, 1, 1, 1);
+    // The Background pseudo-row: it selects the slide and shows the Design panel's background section.
+    const background = treeItem(dom, { level: 2, selected: false, setsize: visibleChildren(s, s.slideKey).length + 1, posinset: visibleChildren(s, s.slideKey).length + 1, attributes: { "data-key": "#background", "data-kind": "background" }, className: `${p}-row` });
+    const backgroundLabel = el("span", `${p}-row-label`);
+    backgroundLabel.style.setProperty("--opf-studio-level", "1");
+    backgroundLabel.append(el("span", `${p}-caret`, { "aria-hidden": "true" }), dom.icon("Image", 14), el("span", `${p}-row-text`, { text: "Background" }));
+    background.append(backgroundLabel);
+    rows.push({ row: background, key: "#background", node: null, level: 2, expandable: false, expanded: false });
+    const slideGroup = items[0]?.querySelector(":scope > ul");
+    if (slideGroup) slideGroup.append(background);
+    else { const group = el("ul", `${p}-tree-group`, { role: "group" }); group.append(background); items[0]?.append(group); }
+    tree.replaceChildren(...items);
+    paintSelection({ focus: hadFocus });
+  }
+
+  /** Mark the selection and the tab stop without rebuilding (`focus`: move focus to the stop). */
+  function paintSelection({ focus = false } = {}) {
+    if (scene() !== lastScene) { render(); return; }
+    const selected = new Set(studio.selectedKeys());
+    const primary = studio.primaryKey();
+    for (const entry of rows) entry.row.setAttribute("aria-selected", String(entry.key !== "#background" && selected.has(entry.key)));
+    const stop = (focus ? null : rows.find((entry) => entry.key === (focusKey && tree.contains(doc.activeElement) ? focusKey : primary))) ?? rows.find((entry) => entry.key === primary) ?? rows[0];
+    if (focus && stop) focusKey = stop.key;
+    rovingTabStop(rows.map((entry) => entry.row), stop?.row);
+    if (focus && stop) stop.row.focus({ preventScroll: false });
+    else if (stop && !tree.contains(doc.activeElement)) stop.row.scrollIntoView?.({ block: "nearest" });
+  }
+
+  function toggle(key) {
+    if (collapsed.has(key)) collapsed.delete(key); else collapsed.add(key);
+    focusKey = key;
+    render();
+    rows.find((entry) => entry.key === key)?.row.focus();
+  }
+  const rowOf = (target) => rows.find((entry) => entry.row === target.closest?.(`.${p}-row`));
+
+  function activate(entry, event) {
+    if (entry.key === "#background") { studio.select([scene().slideKey], { source: "layers" }); studio.showDesignSection("background"); return; }
+    if (event.shiftKey) studio.selectRange(entry.key, { source: "layers" });
+    else if (event.metaKey || event.ctrlKey) studio.selectAdd(entry.key, { source: "layers" });
+    else studio.select([entry.key], { source: "layers" });
+  }
+  tree.addEventListener("click", (event) => {
+    const entry = rowOf(event.target);
+    if (!entry || drag?.moved) return;
+    focusKey = entry.key;
+    activate(entry, event);
+    entry.row.focus({ preventScroll: true });
+  });
+  tree.addEventListener("focusin", (event) => { const entry = rowOf(event.target); if (entry) focusKey = entry.key; });
+  tree.addEventListener("keydown", (event) => {
+    if (isTypingTarget(event.target)) return;
+    const entry = rowOf(event.target);
+    if (!entry) return;
+    const visible = rows.map((item) => item.row);
+    const parentRow = entry.node?.parent ? rows.find((item) => item.key === entry.node.parent)?.row : entry.key === "#background" ? rows[0]?.row : null;
+    const firstChild = entry.expanded ? rows[rows.indexOf(entry) + 1]?.row : null;
+    if (event.key === "F2" && entry.node) { event.preventDefault(); studio.select([entry.key], { source: "layers" }); studio.beginTextEdit(entry.key); return; }
+    if (event.key === "Enter" && !event.shiftKey && !event.metaKey && !event.ctrlKey) {
+      event.preventDefault();
+      event.stopPropagation();
+      activate(entry, {});
+      studio.focusCanvas();
+      return;
+    }
+    if ((event.key === "ContextMenu" || (event.key === "F10" && event.shiftKey)) && entry.node) {
+      event.preventDefault();
+      if (!studio.selectedKeys().includes(entry.key)) studio.select([entry.key], { source: "layers" });
+      const box = entry.row.getBoundingClientRect();
+      studio.openContextMenu({ x: box.left + 24, y: box.bottom }, { returnFocus: entry.row });
+      return;
+    }
+    const action = treeKeyAction(event, entry.row, visible, { expandable: entry.expandable, expanded: entry.expanded, collapsible: entry.expandable, parent: parentRow, firstChild, menu: false });
+    if (!action || action.type === "activate" || action.type === "menu") {
+      if (event.key === " ") { event.preventDefault(); activate(entry, event); }
+      return;
+    }
+    event.preventDefault();
+    event.stopPropagation();
+    if (action.type === "expand" || action.type === "collapse") { toggle(entry.key); return; }
+    const target = rows.find((item) => item.row === action.target);
+    if (!target) return;
+    focusKey = target.key;
+    rovingTabStop(visible, target.row);
+    target.row.focus();
+    if (target.key !== "#background" && !event.shiftKey) studio.select([target.key], { source: "layers" });
+    else if (event.shiftKey && target.key !== "#background") studio.selectRange(target.key, { source: "layers" });
+  });
+
+  // --- drag to reorder or move into a container -------------------------------------------------------------------------------------------
+  tree.addEventListener("pointerdown", (event) => {
+    const entry = rowOf(event.target);
+    if (!entry?.node?.can?.move || studio.readOnly || (event.pointerType === "mouse" && event.button !== 0)) return;
+    drag = { entry, x: event.clientX, y: event.clientY, id: event.pointerId, moved: false, drop: null };
+  });
+  const dropFor = (clientY) => {
+    const target = hitRow(rows.filter((item) => item.node), clientY);
+    if (!target) return null;
+    const box = target.row.querySelector(`.${p}-row-label`).getBoundingClientRect();
+    const node = target.node;
+    const container = node.kind === "slide" || node.kind === "group" || node.kind === "region";
+    const mode = rowDropMode((clientY - box.top) / Math.max(1, box.height), { root: node.kind === "slide", container });
+    const keys = studio.selectedKeys().includes(drag.entry.key) ? studio.selectedKeys() : [drag.entry.key];
+    let targetKey, index;
+    if (mode === "into") { targetKey = node.key; index = scene().contentChildren(node.key).length; }
+    else {
+      if (!node.parent) return null;
+      targetKey = node.parent;
+      const list = scene().contentChildren(node.parent);
+      index = list.findIndex((child) => child.key === node.key) + (mode === "after" ? 1 : 0);
+      if (index < 0) return null;
+    }
+    const trial = adapter.trialMove(keys, targetKey, index);
+    return { keys, target: targetKey, index, mode, box, ...trial };
+  };
+  tree.addEventListener("pointermove", (event) => {
+    if (!drag || event.pointerId !== drag.id) return;
+    if (!drag.moved && Math.hypot(event.clientX - drag.x, event.clientY - drag.y) < 4) return;
+    if (!drag.moved) { drag.moved = true; try { tree.setPointerCapture?.(event.pointerId); } catch { /* a pointer that cannot be captured (a synthetic one) */ } if (!studio.selectedKeys().includes(drag.entry.key)) studio.select([drag.entry.key], { source: "layers" }); }
+    drag.drop = dropFor(event.clientY);
+    showTreeDrop(mark, scroller, drag.drop ? { mode: drag.drop.mode, state: drag.drop.ok ? (drag.drop.noop ? "same" : "ok") : "refused", reason: drag.drop.reason, box: drag.drop.box } : null);
+    if (drag.drop && !drag.drop.ok) studio.status(drag.drop.reason);
+  });
+  const endDrag = (commit) => {
+    const session = drag;
+    drag = null;
+    showTreeDrop(mark, scroller, null);
+    if (!session?.moved || !commit) return;
+    // The click that follows a drag must not select the row under the pointer.
+    drag = { moved: true };
+    globalThis.setTimeout(() => { if (drag?.moved && !drag.entry) drag = null; }, 0);
+    const found = session.drop;
+    if (!found) return;
+    if (!found.ok) { studio.announce(found.reason); return; }
+    if (!found.noop) studio.move(found.keys, found.target, found.index);
+  };
+  tree.addEventListener("pointerup", () => endDrag(true));
+  tree.addEventListener("pointercancel", () => endDrag(false));
+  tree.addEventListener("keydown", (event) => { if (event.key === "Escape" && drag?.moved) { event.preventDefault(); event.stopPropagation(); endDrag(false); studio.announce("Move cancelled."); } }, true);
+
+  return {
+    element: scroller,
+    render,
+    paintSelection,
+    focus() { (rows.find((entry) => entry.row.tabIndex === 0) ?? rows[0])?.row.focus(); },
+    destroy() { scroller.remove(); },
+  };
+}

package/dist/studio.d.ts

@@ -0,0 +1,31 @@
+/**
+ * CE-20 (internal): the Studio's shell and controller. Hosts use `createOpfEditor(el, { layout: "studio" })` from
+ * `@openpresentation/opf-editor/workspace`; the workspace calls these.
+ */
+import type { KitDom } from "./studio-kit/dom.js";
+import type { OpfCommand, OpfCommandInfo, OpfEditorSlots, OpfStudioOptions, OpfStudioSelectionItem } from "./workspace.js";
+import type { SlideAdapter } from "./slide-adapter.js";
+
+export interface StudioShell {
+  dom: KitDom;
+  [element: string]: unknown;
+}
+export declare function buildStudioShell(root: HTMLElement, options: { parts: Record<string, boolean>; layout: "studio" | "playground"; labels?: Record<string, string>; studio?: OpfStudioOptions; slots?: OpfEditorSlots }): { slots: OpfEditorSlots & Record<string, HTMLElement>; controls: { undo: HTMLButtonElement; redo: HTMLButtonElement }; shell: StudioShell };
+export interface Studio {
+  readonly layout: "studio" | "playground";
+  readonly selection: readonly OpfStudioSelectionItem[];
+  readonly zoom: number;
+  readonly adapter: SlideAdapter;
+  readonly commands: { list(): OpfCommandInfo[]; run(id: string): boolean; register(command: OpfCommand): () => void };
+  setLayout(layout: "studio" | "playground"): boolean;
+  select(keys: string[], options?: { source?: string }): void;
+  selectTargets(keysOrPaths: string | string[]): boolean;
+  revealPath(path: string): boolean;
+  setZoom(zoom: number): number;
+  fit(mode?: "slide" | "width"): number;
+  openLayout(layoutId?: string, options?: { slide?: number }): boolean;
+  showTab(id: string, options?: { focus?: boolean }): boolean;
+  refresh(): void;
+  destroy(): void;
+}
+export declare function createStudio(context: Record<string, any>): Studio;