@openpresentation/opf-editor 0.27.0 → 0.29.0

package/dist/thumbnail-cache.d.ts

@@ -17,6 +17,8 @@ export interface ThumbnailCache {
   prepare(presentation: any, indices?: number[]): void;
   /** The SVG markup (or the text "Preview unavailable") of one slide. Entries are keyed by the slide's index, the slide count and the slide's own content. */
   html(presentation: any, index: number): string;
+  /** CE-20: the cached thumbnail of one slide, or undefined when it has not been drawn yet (a lazy strip calls `prepare` with the visible slides). */
+  peek(presentation: any, index: number): string | undefined;
   /** Forget everything, for example after fonts load. */
   clear(): void;
 }

package/dist/thumbnail-cache.js

@@ -6,6 +6,7 @@ export function createThumbnailCache({toSvg, getOptions}) {
   const cache = new Map();
   let context;
   let preparedDeck;
+  let peeked = { deck: null, same: false };
   const key = (deck, index) => JSON.stringify([index, deck.slides.length, deck.slides[index]]);
   const contextOf = (deck, options) => {
     const {slides, ...metadata} = deck;
@@ -19,6 +20,7 @@ export function createThumbnailCache({toSvg, getOptions}) {
     if (nextContext !== context) cache.clear();
     context = nextContext;
     preparedDeck = deck;
+    peeked = { deck: null, same: false };
     const keys = deck.slides.map((_, index) => key(deck, index));
     const wanted = indices === undefined ? keys.map((_, index) => index) : [...new Set(indices)].filter(index => Number.isInteger(index) && index >= 0 && index < keys.length);
     const missing = wanted.filter(index => !cache.has(keys[index]));
@@ -45,6 +47,13 @@ export function createThumbnailCache({toSvg, getOptions}) {
       if (deck !== preparedDeck || !cache.has(value)) prepare(deck);
       return cache.get(value);
     },
-    clear: () => { cache.clear(); preparedDeck = undefined; },
+    /** CE-20: the cached thumbnail of a slide, or undefined when it has not been drawn yet (a lazy strip draws it with `prepare`). */
+    peek(deck, index) {
+      // The context of a deck is read once per deck (a strip peeks at every slide of it in one render).
+      if (peeked.deck !== deck) peeked = { deck, same: contextOf(deck, getOptions()) === context };
+      if (!peeked.same) return undefined;
+      return cache.get(key(deck, index));
+    },
+    clear: () => { cache.clear(); preparedDeck = undefined; peeked = { deck: null, same: false }; },
   };
 }

package/dist/workspace-measure.js

@@ -1,16 +1,18 @@
-// CE-06 (promoted from examples/playground.js): text measurement and font notes shared by the workspace parts.
-import { createScriptTextMeasurement } from "@openpresentation/opf-render/fonts";
+// CE-06 (promoted from examples/playground.js): text measurement and font notes shared by the workspace parts. No renderer import: the script
+// planner comes with the fonts handle (`textMeasurement.forScripts`, the renderer's font registry), so the `/workspace` entry, which re-exports
+// `layoutOptionsFor`, loads no renderer code for a host that mounts only the source pane.
 import { resolveScriptFonts } from "@openpresentation/opf/composition";
 
 /**
  * The layout options for composing slide `index` of `deck`: the fonts handle's measurement, made script-aware for this document (Japanese
  * under Aptos measures with Noto Sans JP, where the plain strict measurement would throw "cannot display U+65E5" with every face loaded).
- * A fonts handle without a measurement is passed through.
+ * A fonts handle without a measurement, or whose measurement has no script planner (`forScripts`), is passed through.
  */
 export function layoutOptionsFor(fonts, deck, index, catalogs) {
   if (!fonts?.textMeasurement) return fonts ? { fonts } : {};
+  if (typeof fonts.textMeasurement.forScripts !== "function") return { fonts };
   try {
-    return { fonts: { textMeasurement: createScriptTextMeasurement(fonts.textMeasurement, resolveScriptFonts(deck, { slideIndex: index, catalogs })) } };
+    return { fonts: { textMeasurement: fonts.textMeasurement.forScripts(resolveScriptFonts(deck, { slideIndex: index, catalogs })) } };
   } catch {
     return { fonts };
   }

package/dist/workspace-parts.js

@@ -0,0 +1,20 @@
+// The slide half of `createOpfEditor` (src/workspace.js), loaded on demand: the renderer, every part that shows or edits slides and the Studio. A host
+// whose editor mounts only the source pane never loads this chunk (and so never loads the renderer); every other layout loads it once, before
+// its parts mount. Internal: only workspace.js imports it.
+export { toSvg } from "@openpresentation/opf-render/svg";
+export { createCanvasEditor } from "./canvas.js";
+export { createSlideNavigator } from "./slide-navigator.js";
+export { createThumbnailStrip } from "./thumbnail-strip.js";
+export { createThumbnailCache } from "./thumbnail-cache.js";
+export { createSlideManager } from "./slide-manager.js";
+export { createOutlineView } from "./outline-view.js";
+export { createExportMenu } from "./export-menu.js";
+export { bindPresentShortcut, createPresentButton, createPresenter } from "./presenter.js";
+export { createReviewPanel } from "./review-panel.js";
+export { createFindPanel, installFindShortcuts } from "./find-panel.js";
+export { createDesignControls } from "./design-controls.js";
+export { prepareDimensionSwitch } from "./switches.js";
+export { mergeSlides, splitSlideByBlocks } from "./content-actions.js";
+export { installCanvasVariableEditing } from "./canvas-variables.js";
+export { createLayoutStudio } from "./workspace-layouts.js";
+export { buildStudioShell, createStudio } from "./studio.js";

package/dist/workspace-shell.js

@@ -50,25 +50,35 @@ export function buildWorkspaceShell(root, { parts, views, layout, labels = {} })
   if (parts.present) bar.append(slot("present", "div", { class: "opf-ws-present" }));
   const hasBar = bar.children.length > 1;
 
-  // The main column: the slide (or another view) over the slide row.
-  const stage = make(doc, "div", { class: "opf-ws-stage" });
-  const frame = make(doc, "div", { class: "opf-ws-frame" }, slot("canvas", "div", { class: "opf-ws-canvas", "aria-label": "Slide preview" }));
-  stage.append(frame);
-  for (const view of ["sorter", "outline", "layouts"]) if (parts[view]) stage.append(slot(view, "div", { class: `opf-ws-view opf-ws-${view}`, hidden: true }));
-  const main = make(doc, "section", { class: "opf-ws-main", "aria-label": "Slide workspace" });
-  if (parts.find) main.append(slot("find", "div", { class: "opf-ws-find", hidden: true }));
-  main.append(stage);
-  if (parts.navigator || parts.thumbnails) {
-    const dock = make(doc, "div", { class: "opf-ws-dock" });
-    if (parts.navigator) dock.append(slot("navigator", "div", { class: "opf-ws-navigator" }));
-    if (parts.thumbnails) dock.append(slot("thumbnails", "div", { class: "opf-ws-thumbnails" }));
-    main.append(dock);
+  // The main column: the slide (or another view) over the slide row, and the status line. A source-only layout has none: the pane has its own
+  // bar, problems and status.
+  const viewParts = ["sorter", "outline", "layouts"].filter((view) => parts[view]);
+  const hasMain = parts.canvas || parts.find || parts.navigator || parts.thumbnails || viewParts.length > 0;
+  let stage;
+  let frame;
+  let main;
+  if (hasMain) {
+    stage = make(doc, "div", { class: "opf-ws-stage" });
+    if (parts.canvas) {
+      frame = make(doc, "div", { class: "opf-ws-frame" }, slot("canvas", "div", { class: "opf-ws-canvas", "aria-label": "Slide preview" }));
+      stage.append(frame);
+    }
+    for (const view of viewParts) stage.append(slot(view, "div", { class: `opf-ws-view opf-ws-${view}`, hidden: true }));
+    main = make(doc, "section", { class: "opf-ws-main", "aria-label": "Slide workspace" });
+    if (parts.find) main.append(slot("find", "div", { class: "opf-ws-find", hidden: true }));
+    main.append(stage);
+    if (parts.navigator || parts.thumbnails) {
+      const dock = make(doc, "div", { class: "opf-ws-dock" });
+      if (parts.navigator) dock.append(slot("navigator", "div", { class: "opf-ws-navigator" }));
+      if (parts.thumbnails) dock.append(slot("thumbnails", "div", { class: "opf-ws-thumbnails" }));
+      main.append(dock);
+    }
+    main.append(slot("status", "p", { class: "opf-ws-status", role: "status" }));
   }
-  main.append(slot("status", "p", { class: "opf-ws-status", role: "status" }));
 
   const body = make(doc, "div", { class: "opf-ws-body" });
   if (parts.source) body.append(make(doc, "section", { class: "opf-ws-source", "aria-label": "OPF source" }, slot("source", "div", { class: "opf-ws-source-host" })));
-  body.append(main);
+  if (main) body.append(main);
 
   // The side panel: Review and Design as tabs.
   const tabs = ["design", "review"].filter((name) => parts[name]);

package/dist/workspace-theme.js

@@ -23,6 +23,9 @@ export const THEME_TOKENS = Object.freeze({
   success: "--opf-ui-success",
   codeBackground: "--opf-ui-code-bg",
   codeBorder: "--opf-ui-code-border",
+  selection: "--opf-ui-selection",
+  hover: "--opf-ui-hover",
+  canvasBackground: "--opf-ui-studio-canvas-bg",
   font: "--opf-ui-font",
   mono: "--opf-ui-mono",
   radiusSmall: "--opf-ui-radius-sm",

package/dist/workspace.d.ts

@@ -11,9 +11,9 @@ import type { Presenter } from "./presenter.js";
 import type { ReviewFinding, ReviewHook } from "./review.js";
 import type { ReviewPanel, ReviewPanelOptions } from "./review-panel.js";
 import type { SlideManager } from "./slide-manager.js";
-import type { SourceFormat, SourceFile, SourcePane, SourcePaneOptions } from "./source-pane.js";
+import type { SourceCursor, SourceFormat, SourceFile, SourcePane, SourcePaneOptions } from "./source-pane.js";
 
-export type OpfEditorLayout = "full" | "canvas" | "source";
+export type OpfEditorLayout = "full" | "canvas" | "source" | "studio" | "playground";
 export type OpfEditorView = "slide" | "sorter" | "outline" | "layouts";
 export type OpfEditorDensity = "comfortable" | "touch";
 
@@ -36,6 +36,9 @@ export declare const THEME_TOKENS: Readonly<{
   success: "--opf-ui-success";
   codeBackground: "--opf-ui-code-bg";
   codeBorder: "--opf-ui-code-border";
+  selection: "--opf-ui-selection";
+  hover: "--opf-ui-hover";
+  canvasBackground: "--opf-ui-studio-canvas-bg";
   font: "--opf-ui-font";
   mono: "--opf-ui-mono";
   radiusSmall: "--opf-ui-radius-sm";
@@ -77,6 +80,19 @@ export interface ThemeController {
 /** Apply a theme to the editor mounted in `root`. `createOpfEditor` does this for `options.theme` and `handle.setTheme`. */
 export declare function createThemeController(root: HTMLElement, theme?: OpfEditorTheme): ThemeController;
 
+/**
+ * The options for composing slide `slideIndex` of `deck` with the fonts handle `fonts`: its text measurement, made script-aware for this document
+ * (Japanese under Aptos measures with Noto Sans JP, where the plain strict measurement would throw). Pass the result to the session's
+ * `composeSlide` and `paginateSlide`, and the same `catalogs` the editor was given. Without a handle it is `{}`, and a handle without a
+ * measurement is passed through.
+ */
+export declare function layoutOptionsFor(
+  fonts: EditorFonts | undefined,
+  deck: unknown,
+  slideIndex: number,
+  catalogs?: readonly Catalog[],
+): { fonts?: EditorFonts };
+
 /** What a host's own acquire function returns: the handle and the way to give it back. */
 export interface OpfEditorFontsLease {
   fonts: EditorFonts;
@@ -127,6 +143,42 @@ export interface OpfEditorSlots {
   /** The status line: the editor writes its messages here. */
   status?: HTMLElement;
   overlay?: HTMLElement;
+  /** CE-20, the Studio: an element of the host placed at the end of the Studio's bar (Share, avatars). */
+  topbarEnd?: HTMLElement;
+}
+
+/** CE-20: one item of the Studio's selection. `key` is the scene key (the id path, `/slides/@intro/blocks/@kpi`; a layout region `<slide key>#<name>`). */
+export interface OpfStudioSelectionItem { key: string; path: string; idPath?: string; kind: "slide" | "heading" | "region" | "group" | "block" | "part" | "implicit" }
+/** CE-20: a command of the Studio's registry (`studio.group`, `studio.insert.chart`, ...). `when` returns true, or a reason string that disables it. */
+export interface OpfCommand<Ctx = unknown> {
+  id: string;
+  label: string;
+  group?: string;
+  /** CodeMirror-style keys ("Mod-g", "Shift-Mod-z", "F2"); Mod is Cmd on macOS and Ctrl elsewhere. */
+  keys?: string[];
+  /** "canvas": only while focus is on the slide, the layers or the filmstrip; "global" (default) anywhere outside a field. */
+  scope?: "canvas" | "global" | ("canvas" | "global")[];
+  when?(ctx: Ctx): boolean | string;
+  run(ctx: Ctx): boolean | void;
+}
+export interface OpfCommandInfo { id: string; label: string; group?: string; keys: string[]; shortcut: string; enabled: boolean; reason: string }
+/** CE-20: a host's panel in the Studio: a tab of the right panel (default) or a section of the left (`side: "left"`); `mount` returns its cleanup. */
+export interface OpfStudioHostPanel { id: string; label: string; icon?: SVGElement | string; side?: "left" | "right"; mount(element: HTMLElement, editor: OpfEditor): void | (() => void) }
+/** CE-20: the Studio's options (`layout: "studio"` or `"playground"`). */
+export interface OpfStudioOptions {
+  /** Which panels the Studio shows; `source` is where the source split opens ("split-right" by default on wide screens, "split-bottom" below 1100px). */
+  panels?: { source?: "split-right" | "split-bottom" | "tab" | false };
+  hostPanels?: OpfStudioHostPanel[];
+  /** Items added to the File menu. */
+  fileItems?: { id: string; label: string; run(editor: OpfEditor): void }[];
+  /** More commands for the registry (a host palette lists them with the Studio's). */
+  commands?: OpfCommand[];
+  /** Rebind commands: `{ "studio.source.toggle": ["Mod-Alt-s"] }`; `null` unbinds. */
+  keymap?: Record<string, string[] | null>;
+  /** Panel sizes stored per host key (nothing is stored without `storage`). */
+  sizes?: { key: string; storage?: { get(key: string): string | null; set(key: string, value: string): void } };
+  /** Give a deck without ids its ids when the Studio opens it (default true; one undoable change named "Add ids"). Never in the Playground. */
+  assignIds?: boolean;
 }
 
 export interface OpfEditorPanels {
@@ -162,12 +214,14 @@ export interface OpfEditorSourceOptions {
   name?: string;
   /** The text of the document as the author wrote it, so its spelling is kept. A string `document` is used when this is not given. */
   text?: string;
-  /** The Web Worker that runs the pane's text checks off the main thread: `true`, a `Worker`, or a function that returns one. Default: the main thread. */
+  /** The Web Worker that runs the pane's text checks off the main thread: `true`, a `Worker`, a function that returns one, or the URL of a worker script (docs/embedding.md, "The source worker"). Default: the main thread. */
   worker?: SourcePaneOptions["worker"];
   /** Core `validate` options for the verdict on the text (default the format and reference rules). */
   checks?: { only?: readonly string[]; [key: string]: unknown };
   outline?: SourcePaneOptions["outline"];
   applyDelay?: number;
+  /** Milliseconds of quiet before a `cursor` event (default 50). */
+  cursorDelay?: number;
   completions?: boolean;
   label?: string;
   catalogs?: SourcePaneOptions["catalogs"];
@@ -196,8 +250,15 @@ export interface OpfEditorOptions {
   /** `"authored"` (default): the canvas shows `{{variables}}` as written. `"resolved"`: filled in, except in a template deck; a press on filled-in text opens its properties form. */
   variables?: "authored" | "resolved";
 
-  /** `"full"` (default), `"canvas"` or `"source"`: the editor builds the arrangement. Ignored when `slots` is given. */
+  /**
+   * `"full"` (default), `"canvas"` or `"source"`: the editor builds the arrangement (ignored when `slots` is given). CE-20: `"studio"` is the
+   * Presentation and Slide Studio and `"playground"` its first-contact preset (a host's `slots` then add parts, such as `topbarEnd`).
+   */
   layout?: OpfEditorLayout;
+  /** CE-20: the Studio's options. */
+  studio?: OpfStudioOptions;
+  /** CE-20: `import.pptx(editor)` adds "Import PowerPoint…" to the Studio's File menu. */
+  import?: { pptx?(editor: OpfEditor): void };
   slots?: OpfEditorSlots;
   panels?: OpfEditorPanels;
   /** The view shown first (default `"slide"`). */
@@ -240,6 +301,8 @@ export interface OpfEditorOptions {
 
   onChange?(detail: OpfEditorEvents["change"]): void;
   onSelection?(detail: OpfEditorEvents["selection"]): void;
+  /** The caret of the source pane moved to another place in the text. The same as `on: { cursor }`. */
+  onCursor?(detail: OpfEditorEvents["cursor"]): void;
   onError?(error: Error, detail: Omit<OpfEditorEvents["error"], "error">): void;
   onReady?(detail: OpfEditorEvents["ready"]): void;
   /** Listeners by event name; the same as calling `on` before anything happens. */
@@ -260,7 +323,22 @@ export interface OpfEditorEvents {
   ready: { editor: OpfEditor };
   /** The document changed (an edit in the canvas or the source, undo, redo, a loaded document). Not fired for a catalogs change. */
   change: { document: unknown; canUndo: boolean; canRedo: boolean; event: EditorEvent };
-  selection: { path: string; value: unknown; slideIndex: number; element: Element | undefined };
+  /** The canvas's selection; in the Studio, the list (`items`, the `primary` and what changed it: `canvas`, `layers`, `keyboard`, `source`, ...). */
+  selection: { path: string | undefined; value: unknown; slideIndex: number; element?: Element | undefined; items?: OpfStudioSelectionItem[]; primary?: OpfStudioSelectionItem | null; source?: string };
+  /** CE-20: the Studio's zoom changed (a factor of the fitted slide). */
+  zoom: { zoom: number };
+  /** CE-20: the Studio switched preset. */
+  layout: { layout: "studio" | "playground"; previous: "studio" | "playground" };
+  /** CE-20: a Studio command ran (`ok` false when it was off; `reason` says why). */
+  command: { id: string; ok: boolean; reason?: string };
+  /** CE-20: Layout Studio was opened from "Edit layout", or closed. */
+  layoutStudio: { open: boolean; recordId: string };
+  /**
+   * The caret or selection of the source pane moved, in JSON, YAML or Markdown, also while the pane has no focus: the path under it as a JSON Pointer
+   * and by id, and the selection in source offsets. Quiet for `source.cursorDelay` first and not repeated for a place already reported; the detail is
+   * frozen. For the rest of the pane (`revealPath`, `setDecorations`, `getCursor`) use `editor.sourcePane`.
+   */
+  cursor: SourceCursor;
   /** The slide changed (0-based). */
   slide: { index: number; count: number };
   view: { view: OpfEditorView; previous: OpfEditorView };
@@ -326,13 +404,26 @@ export interface OpfEditor {
   readonly layoutStudio: LayoutStudio | undefined;
   readonly fonts: EditorFonts | undefined;
   readonly slideIndex: number;
-  /** The content last selected on the canvas. */
-  readonly selection: { path: string; value: unknown } | null;
+  /** The content last selected on the canvas; in the Studio, the selection list. */
+  readonly selection: { path: string; value: unknown } | OpfStudioSelectionItem[] | null;
+  /** CE-20: the arrangement; `setLayout` switches the Studio between "studio" and "playground". */
+  readonly layout: OpfEditorLayout | "slots";
+  setLayout(layout: "studio" | "playground"): boolean;
+  /** CE-20: the Studio's zoom (1 is the slide fitted), `setZoom` and `fit` ("slide" or "width"). */
+  readonly zoom: number;
+  setZoom(zoom: number): void;
+  fit(mode?: "slide" | "width"): void;
+  /** CE-20: "Edit layout": open a layout of the slide (default the current slide's) in Layout Studio, forked into the deck when it comes from a catalog. */
+  openLayout(layoutId?: string, options?: { slide?: number }): boolean;
+  /** CE-20: the Studio's command registry; empty outside the Studio. */
+  readonly commands: { list(): OpfCommandInfo[]; run(id: string): boolean; register(command: OpfCommand): () => void };
   readonly view: OpfEditorView;
   readonly views: OpfEditorView[];
   readonly readOnly: boolean;
   /** False while the text in the source pane is not a valid deck: the slide shows the last valid one. */
   readonly inSync: boolean;
+  /** The latest `cursor` event, or `null` before the first (and without a source pane). The same object until the next event. */
+  readonly sourceCursor: SourceCursor | null;
   /** The latest verdict on the text of the source pane (what the last `source` event carried), or `null` before the first. */
   readonly sourceState: OpfEditorSourceState | null;
   readonly lastError: Error | undefined;
@@ -344,6 +435,14 @@ export interface OpfEditor {
    * as written. A document the session refuses is listed in the pane as a draft and `false` is returned. Throws before `ready`.
    */
   setDocument(document: unknown, options?: OpfEditorSetDocumentOptions): boolean;
+  /**
+   * Load raw source text into the source pane without converting it (a file as it was read, text that does not parse): what pasting it over
+   * everything does. `options.format` is the text's format (the pane switches to it), `options.name` the file name, `options.rebase` as in
+   * `setDocument` (only when the text applied). Text that reads as a document the session accepts is applied as one undoable change; anything
+   * else stays in the pane as a draft with its problems (the slide keeps the last valid document) and `false` is returned. An open canvas edit
+   * is committed first. Throws before `ready`, without a source pane, and while read-only.
+   */
+  setSourceText(text: string, options?: Omit<OpfEditorSetDocumentOptions, "text">): boolean;
   /** Switch the view. Commits an open canvas edit first; false when that failed or the view is not available. */
   setView(view: OpfEditorView, options?: { focus?: boolean }): boolean;
   /** Show slide `index` (0-based). Commits an open canvas edit first. */
@@ -355,10 +454,12 @@ export interface OpfEditor {
   /** Show a slide and select the content at `path` on it. */
   goTo(index: number, path?: string): boolean;
   /** Select the content at `path` on the current slide (or the closest content that can be selected); returns the path selected. */
-  select(path: string, options?: { focus?: boolean }): string | null;
+  /** Select content by path (the canvas: returns the path it selected). In the Studio: scene keys or paths, several siblings at once; returns whether all were found. */
+  select(path: string | string[], options?: { focus?: boolean }): string | null | boolean;
   showPanel(panel: "review" | "design", focus?: boolean): boolean;
   /** Start the full-screen presentation at the slide on show. False when it cannot start (invalid source, no slides, already running). */
-  present(): boolean;
+  /** Present from the slide on show (or from `from`, 0-based). */
+  present(from?: number): boolean;
   undo(): boolean;
   redo(): boolean;
   /** Commit an open canvas edit. False when it could not be committed. */
@@ -382,7 +483,10 @@ export interface OpfEditor {
   destroy(): void;
 }
 
-/** Mount the editor in `element` (its content is replaced). */
+/**
+ * Mount the editor in `element` (its content is replaced). The parts mount once the fonts have arrived and, for a layout that shows slides,
+ * once the slide chunk (the renderer and the slide parts, imported on demand) has loaded; await `ready`. A source-only editor never loads that chunk.
+ */
 export declare function createOpfEditor(element: HTMLElement, options?: OpfEditorOptions): OpfEditor;
 
 export type { LayoutStudio } from "./workspace-layouts.js";