@openpresentation/opf-editor 0.27.0 → 0.29.0

package/dist/studio-kit/commands.js

@@ -0,0 +1,148 @@
+// CE-18, the studio kit: the command registry and keymap. A command is `{ id, label, group, scope, keys, hint, repeat, when, run }`; the
+// keyboard, the context menu, the bar's disabled states, the shortcut sheet and a host palette all read one registry, so they cannot drift.
+// Keys are CodeMirror-style strings ("Mod-z", "Shift-Mod-z", "Ctrl-y", "[", "Shift-[", "Delete", "F2"). No DOM beyond the event it is given.
+import { isMac, isTypingTarget } from "./dom.js";
+
+const HANDLED = "opfStudioHandled";
+/** Whether an earlier handler already acted on this key event. */
+export const isHandled = (event) => Boolean(event?.[HANDLED]);
+/** Mark a key event as acted on, so the handlers it bubbles to leave it alone. */
+export const markHandled = (event) => { event[HANDLED] = true; };
+/** Whether a shortcut may act on this event: not handled already, not prevented, not typed into a field, not an IME composition. */
+export const keyGuard = (event) => !(isHandled(event) || event.defaultPrevented || isTypingTarget(event.target) || event.isComposing);
+
+// A key can also be matched by its physical position, so a keyboard layout where "[" needs AltGr (or Shift turns it into "{") still has it.
+const CODES = { "[": "BracketLeft", "]": "BracketRight" };
+const MODIFIERS = new Set(["Shift", "Alt", "Mod", "Ctrl", "Meta", "Cmd"]);
+
+/** Parse "Shift-Mod-z" into `{ key, shift, alt, mod, ctrl, meta }`. A trailing "-" is the minus key ("Mod--"). */
+export function parseKey(spec) {
+  const text = String(spec);
+  if (text === "-") return { key: "-", shift: false, alt: false, mod: false, ctrl: false, meta: false };
+  const parts =text.endsWith("-") && text.length > 1 ? [...text.slice(0, -2).split("-").filter(Boolean), "-"] : text.split("-");
+  const key = parts.pop();
+  const out = { key, shift: false, alt: false, mod: false, ctrl: false, meta: false };
+  for (const part of parts) {
+    if (!MODIFIERS.has(part)) throw new TypeError(`Unknown modifier ${part} in ${spec}`);
+    if (part === "Cmd") out.meta = true; else out[part.toLowerCase()] = true;
+  }
+  return out;
+}
+
+/**
+ * Whether a keyboard event matches one key spec. Shift and Alt must be exactly as listed. `Mod` is satisfied by Cmd or Ctrl on every platform
+ * (so a Windows keyboard on a Mac works), `Ctrl` by Ctrl and `Meta`/`Cmd` by Cmd; with none of the three listed, neither Cmd nor Ctrl may be
+ * down. A one-character key compares without case; "[" and "]" also match their physical key.
+ */
+export function matchKey(event, spec) {
+  const want = typeof spec === "string" ? parseKey(spec) : spec;
+  if (Boolean(event.shiftKey) !== want.shift || Boolean(event.altKey) !== want.alt) return false;
+  if (want.mod || want.ctrl || want.meta) {
+    if (want.mod && !(event.metaKey || event.ctrlKey)) return false;
+    if (want.ctrl && !event.ctrlKey) return false;
+    if (want.meta && !event.metaKey) return false;
+  } else if (event.metaKey || event.ctrlKey) return false;
+  const key = event.key ?? "";
+  if (want.key.length === 1) return key.toLowerCase() === want.key.toLowerCase() || (CODES[want.key] !== undefined && event.code === CODES[want.key]);
+  return key === want.key;
+}
+
+const MAC_NAMES = { shift: "⇧", alt: "⌥", ctrl: "⌃", mod: "⌘", meta: "⌘" };
+const PC_NAMES = { shift: "Shift+", alt: "Alt+", ctrl: "Ctrl+", mod: "Ctrl+", meta: "Win+" };
+const KEY_NAMES = { " ": "Space", ArrowUp: "↑", ArrowDown: "↓", ArrowLeft: "←", ArrowRight: "→", Escape: "Esc" };
+/** A key spec as people read it: "⌘D" on a Mac, "Ctrl+D" elsewhere. */
+export function formatKey(spec, win) {
+  const want = typeof spec === "string" ? parseKey(spec) : spec;
+  const mac = isMac(win);
+  const names = mac ? MAC_NAMES : PC_NAMES;
+  const order = mac ? ["ctrl", "alt", "shift", "mod", "meta"] : ["ctrl", "mod", "meta", "alt", "shift"];
+  const mods = order.filter((name) => want[name] && !(name === "ctrl" && want.mod)).map((name) => names[name]).join("");
+  const key = KEY_NAMES[want.key] ?? (want.key.length === 1 ? want.key.toUpperCase() : want.key);
+  return mods + key;
+}
+
+/**
+ * A command registry. `register(command)` returns the function that removes it. A command has an `id`, a `label`, optional `group`,
+ * `scope` (a name or a list of names; `handle` runs only the commands of the scope it is given; default "global"), `keys` (key specs),
+ * `hint` (what a menu shows instead of the formatted first key), `repeat` (false: a held key does not repeat it), `when(ctx)` (true, false,
+ * or a reason string that disables it) and `run(ctx, event)`.
+ */
+export function createCommandRegistry({ commands = [] } = {}) {
+  const byId = new Map();
+  const overrides = new Map();
+  const keysOf = (command) => (overrides.has(command.id) ? overrides.get(command.id) : command.keys) ?? [];
+  const scopesOf = (command) => [].concat(command.scope ?? "global");
+  const state = (command, ctx) => {
+    const verdict = command.when ? command.when(ctx) : true;
+    return verdict === true ? { enabled: true, reason: "" } : { enabled: false, reason: typeof verdict === "string" ? verdict : "" };
+  };
+
+  const registry = {
+    register(command) {
+      if (!command?.id || typeof command.run !== "function") throw new TypeError("A command needs an id and a run function.");
+      if (byId.has(command.id)) throw new Error(`A command ${command.id} is already registered.`);
+      const parsed = { ...command };
+      byId.set(command.id, parsed);
+      return () => { if (byId.get(command.id) === parsed) byId.delete(command.id); };
+    },
+    get: (id) => byId.get(id),
+    has: (id) => byId.has(id),
+    /** Rebind commands: `{ id: keys }` replaces a command's keys, `{ id: null }` unbinds it. */
+    setKeymap(map = {}) {
+      for (const [id, keys] of Object.entries(map)) overrides.set(id, keys === null ? [] : [].concat(keys));
+    },
+    /** Every command with its state for `ctx`: `{ id, label, group, keys, shortcut, enabled, reason }`, in registration order. */
+    list(ctx, { win } = {}) {
+      return [...byId.values()].map((command) => {
+        const keys = keysOf(command);
+        return { id: command.id, label: command.label, group: command.group, keys: [...keys], shortcut: command.hint ?? (keys[0] ? formatKey(keys[0], win) : ""), ...state(command, ctx) };
+      });
+    },
+    /** Whether `id` may run for `ctx` (`when` returned true). */
+    enabled: (id, ctx) => (byId.has(id) ? state(byId.get(id), ctx).enabled : false),
+    /** Run `id` for `ctx` when it is enabled. Returns false when it is unknown or disabled, else what `run` returned (true when it returned nothing). */
+    run(id, ctx, event) {
+      const command = byId.get(id);
+      if (!command || !state(command, ctx).enabled) return false;
+      const result = command.run(ctx, event);
+      return result === undefined ? true : Boolean(result);
+    },
+    /** The command of `scope` a key event would run: the first whose keys match and whose `when` is true. */
+    match(event, ctx, { scope = "global" } = {}) {
+      for (const command of byId.values()) {
+        if (!scopesOf(command).includes(scope)) continue;
+        if (command.repeat === false && event.repeat) continue;
+        if (!keysOf(command).some((spec) => matchKey(event, spec))) continue;
+        if (state(command, ctx).enabled) return command;
+      }
+      return null;
+    },
+    /**
+     * Act on a key event: the guard (`keyGuard`), then the matching command of `scope`. The event is prevented and marked handled, and true
+     * is returned, whether or not the command changed anything.
+     */
+    handle(event, ctx, { scope = "global" } = {}) {
+      if (!keyGuard(event)) return false;
+      const command = registry.match(event, ctx, { scope });
+      if (!command) return false;
+      event.preventDefault();
+      command.run(ctx, event);
+      markHandled(event);
+      return true;
+    },
+    /**
+     * Menu items for `openMenu` from command ids, in order: `{ id, label, hint, disabled, title, onSelect }`. The state is read when the menu
+     * is built; a disabled item cannot be chosen, and choosing an enabled one runs the command for the `ctx` the menu was built with.
+     */
+    menu(ids, ctx, { win } = {}) {
+      return ids.filter((id) => byId.has(id)).map((id) => {
+        const command = byId.get(id);
+        const keys = keysOf(command);
+        const { enabled, reason } = state(command, ctx);
+        return { id, label: command.label, hint: command.hint ?? (keys[0] ? formatKey(keys[0], win) : undefined), disabled: !enabled, title: reason || undefined, onSelect: () => command.run(ctx) };
+      });
+    },
+  };
+  for (const command of commands) registry.register(command);
+  return registry;
+}

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

@@ -0,0 +1,52 @@
+/** CE-18 studio kit (internal): DOM helpers, icons, the menu and the typing-target guard. */
+export declare const ICONS: Readonly<Record<string, string>>;
+/** The default class prefix of kit parts ("opf-kit"); Layout Studio passes "opf-lx". */
+export declare const KIT_PREFIX: string;
+export declare function nextId(prefix: string): string;
+export interface KitButtonOptions {
+  label?: string;
+  text?: string;
+  iconName?: string;
+  size?: number;
+  pressed?: boolean;
+  title?: string;
+  attributes?: Record<string, string | number | boolean | undefined | null>;
+}
+export interface KitDom {
+  doc: Document;
+  prefix: string;
+  el<K extends keyof HTMLElementTagNameMap>(tag: K, className?: string, attributes?: Record<string, string | number | boolean | undefined | null>): HTMLElementTagNameMap[K];
+  icon(name: string, size?: number): SVGSVGElement;
+  button(className: string, options?: KitButtonOptions): HTMLButtonElement;
+}
+export declare function createDom(doc: Document, options?: { prefix?: string }): KitDom;
+export declare function isTypingTarget(target: EventTarget | null): boolean;
+export declare function isMac(win?: Window | null): boolean;
+/** A unit fraction as a CSS percentage. */
+export declare function pct(fraction: number): string;
+export interface KitMenuItem {
+  label: string;
+  onSelect?(): void;
+  disabled?: boolean;
+  role?: "menuitem" | "menuitemcheckbox";
+  checked?: boolean;
+  hint?: string;
+  /** CE-20: a Lucide icon name drawn before the label. */
+  icon?: string;
+  /** CE-20: an element drawn before the label instead of an icon (a layout diagram). */
+  media?: HTMLElement;
+  /** CE-20: a second, quieter line under the label. */
+  description?: string;
+  /** CE-20: the item's title (why it is disabled). */
+  title?: string;
+  /** CE-20: `aria-keyshortcuts`. */
+  keyshortcuts?: string;
+  /** CE-20: consecutive items with the same group sit in a `role="group"` under a visible heading. */
+  group?: string;
+  /** CE-20: a separator instead of an item. */
+  separator?: boolean;
+  /** CE-20: a press on the item (an item that can be dragged out of the menu); `close()` closes the menu without restoring focus. */
+  pointerdown?(event: PointerEvent, item: KitMenuItem, menu: { close(): void }): void;
+}
+export interface KitMenu { element: HTMLElement; close(options?: { restore?: boolean }): void }
+export declare function openMenu(dom: KitDom, host: HTMLElement, options: { x: number; y: number; items: KitMenuItem[]; label: string; returnFocus?: HTMLElement | null; onClose?(): void; className?: string }): KitMenu;

package/dist/studio-kit/dom.js

@@ -0,0 +1,198 @@
+// 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"/>',
+  Video: '<path d="m16 13 5.223 3.482a.5.5 0 0 0 .777-.416V7.87a.5.5 0 0 0-.752-.432L16 10.5"/><rect x="2" y="6" width="14" height="12" rx="2"/>',
+  Gauge: '<path d="m12 14 4-4"/><path d="M3.34 19a10 10 0 1 1 17.32 0"/>',
+  CalendarRange: '<rect width="18" height="18" x="3" y="4" rx="2"/><path d="M16 2v4"/><path d="M3 10h18"/><path d="M8 2v4"/><path d="M17 14h-6"/><path d="M13 18H7"/><path d="M7 14h.01"/><path d="M17 18h.01"/>',
+  Type: '<polyline points="4 7 4 4 20 4 20 7"/><line x1="9" x2="15" y1="20" y2="20"/><line x1="12" x2="12" y1="4" y2="20"/>',
+  Menu: '<line x1="4" x2="20" y1="12" y2="12"/><line x1="4" x2="20" y1="6" y2="6"/><line x1="4" x2="20" y1="18" y2="18"/>',
+  FileCode: '<path d="M10 12.5 8 15l2 2.5"/><path d="m14 12.5 2 2.5-2 2.5"/><path d="M14 2v4a2 2 0 0 0 2 2h4"/><path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7z"/>',
+  PanelLeft: '<rect width="18" height="18" x="3" y="3" rx="2"/><path d="M9 3v18"/>',
+  Presentation: '<path d="M2 3h20"/><path d="M21 3v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V3"/><path d="m7 21 5-5 5 5"/>',
+  Keyboard: '<path d="M10 8h.01"/><path d="M12 12h.01"/><path d="M14 8h.01"/><path d="M16 12h.01"/><path d="M18 8h.01"/><path d="M6 8h.01"/><path d="M7 16h10"/><path d="M8 12h.01"/><rect width="20" height="16" x="2" y="4" rx="2"/>',
+  EyeOff: '<path d="M10.733 5.076a10.744 10.744 0 0 1 11.205 6.575 1 1 0 0 1 0 .696 10.747 10.747 0 0 1-1.444 2.49"/><path d="M14.084 14.158a3 3 0 0 1-4.242-4.242"/><path d="M17.479 17.499a10.75 10.75 0 0 1-15.417-5.151 1 1 0 0 1 0-.696 10.75 10.75 0 0 1 4.446-5.143"/><path d="m2 2 20 20"/>',
+  Ungroup: '<rect width="8" height="6" x="5" y="4" rx="1"/><rect width="8" height="6" x="11" y="14" rx="1"/>',
+  ArrowUp: '<path d="m5 12 7-7 7 7"/><path d="M12 19V5"/>',
+  IndentIncrease: '<path d="M21 12H11"/><path d="M21 18H11"/><path d="M21 6H11"/><path d="m3 8 4 4-4 4"/>',
+  IndentDecrease: '<path d="M21 12H11"/><path d="M21 18H11"/><path d="M21 6H11"/><path d="m7 8-4 4 4 4"/>',
+  ArrowDown: '<path d="M12 5v14"/><path d="m19 12-7 7-7-7"/>',
+  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 });
+  // CE-20: items may carry an `icon` (a Lucide name), a `media` element (a layout diagram), a `description` (a second line), a `title` (why
+  // it is disabled), `pointerdown(event, item)` (an item that can also be dragged out of the menu) and a `group` name: consecutive items of
+  // one group sit in a `role="group"` under a visible heading. `{ separator: true }` draws a separator.
+  let parent = menu, groupName;
+  const buttons = [];
+  for (const item of items) {
+    if (item.separator) { menu.append(dom.el("div", `${p}-menu-separator`, { role: "separator" })); parent = menu; groupName = undefined; continue; }
+    if (item.group !== groupName) {
+      groupName = item.group;
+      if (groupName) {
+        parent = dom.el("div", `${p}-menu-group`, { role: "group", "aria-label": groupName });
+        parent.append(dom.el("div", `${p}-menu-heading`, { "aria-hidden": "true", text: groupName }));
+        menu.append(parent);
+      } else parent = menu;
+    }
+    const role = item.role ?? "menuitem";
+    const node = dom.el("button", `${p}-menuitem`, { type: "button", role, tabindex: "-1", title: item.title, "aria-disabled": item.disabled ? "true" : undefined, "aria-checked": role === "menuitemcheckbox" ? String(Boolean(item.checked)) : undefined, "aria-keyshortcuts": item.keyshortcuts });
+    if (item.media) node.append(item.media);
+    else if (item.icon) node.append(dom.icon(item.icon, 16));
+    if (item.description) {
+      const text = dom.el("span", `${p}-menu-text`);
+      text.append(dom.el("span", `${p}-menu-label`, { text: item.label }), dom.el("span", `${p}-menu-description`, { text: item.description }));
+      node.append(text);
+    } else 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));
+    if (item.pointerdown) node.addEventListener("pointerdown", (event) => item.pointerdown(event, item, { close: () => close({ restore: false }) }));
+    node.addEventListener("click", () => {
+      if (item.disabled) return;
+      close();
+      item.onSelect?.();
+    });
+    parent.append(node);
+    buttons.push(node);
+  }
+  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>;