@onodocs/canvas 0.2.1 → 0.3.0

package/README.md

@@ -60,7 +60,69 @@ Batch range offsets refer to the original paragraph text. Empty ranges insert te
 
 Browser updates rebuild layout and refresh mounted views. Query, semantic, layout, page and geometry values obtained earlier remain snapshots; read them again after updating. Application attachments are removed during refresh and can be reattached using fresh geometry. Updates run in submission order and accept `{ signal }` for cancellation. The original `source` is unchanged.
 
-Node inspection exposes the same update method. For server rendering, inspect the input with the default entry point to select elements or ranges, then pass those updates to the server document before `renderPage` or `pdf`. Exports reflect the updated text. Saving an updated DOCX, structural editing, and field recalculation are not supported.
+Node inspection exposes the same update method. For server rendering, inspect the input with the default entry point to select elements or ranges, then pass those updates to the server document before `renderPage`, `pdf`, or `save`. Exports reflect the updated text.
+
+## Save an edited Word document
+
+`save()` returns DOCX bytes in Node, the browser, and server rendering. Saving without edits returns the original file bytes. Text edits preserve surrounding run formatting and unedited package content. Saving and updating run in submission order. Both accept `{ signal }`; cancellation leaves the committed document available. Call `dispose()` when finished, including for Node documents, to release the preserved source package.
+
+```js
+import { readFile, writeFile } from "node:fs/promises";
+import { openDocument } from "@onodocs/sdk";
+
+const doc = await openDocument(await readFile("template.docx"));
+try {
+  await doc.update({
+    target: doc.query.contentControls().where({ tag: "customer" }).one(),
+    text: "Willow Design"
+  });
+  await writeFile("completed.docx", await doc.save());
+} finally {
+  doc.dispose();
+}
+```
+
+In a browser, create a Blob from the returned bytes with type `application/vnd.openxmlformats-officedocument.wordprocessingml.document`. In a combined deployment, serve `await doc.save()` from an application-owned download endpoint with that content type and a `.docx` filename. The backend processing document owns saving; a Canvas-only frontend does not contain the original Word package.
+
+The SDK package includes a complete command-line example. After installing it, run `node node_modules/@onodocs/sdk/examples/fill-template.mjs template.docx completed.docx customer "Willow Design"`. Set `ONODOCS_LICENSE_KEY` for trial or commercial use. The source workspace keeps the same example at `examples/fill-template.mjs`.
+
+The initial editing profile covers ordinary text and unbound text or rich-text content controls within one paragraph, including supported tables, headers, footers and notes. Edits inside bound or content-locked controls, temporary or specialized controls, fields, revisions, alternate-content branches, and source runs with generated or unsupported content are rejected before publication. Plain-text controls that disallow multiple lines reject newlines. Filling an unbound text control clears its placeholder-display flag. Edits elsewhere preserve these constructs. `DocumentSaveError.reason` identifies source-writing restrictions; existing semantic target errors remain `RangeError`.
+
+Signed packages, enforced document protection, enabled change tracking, macro-enabled documents and templates can be saved unchanged, but editing them is not supported. Field recalculation and revision authoring are not included. Field caches remain as imported, and saved bookmark/comment markers retain their original run boundaries. Original authored formatting is preserved independently of rendering compatibility decisions.
+
+Evaluation exports contain the full Word document without adding a Word watermark. The existing non-production evaluation terms apply; rendered evaluation output continues to include its watermark.
+
+## Edit formatting and paragraphs
+
+`edit()` accepts a logical selection with paragraph IDs and UTF-16 offsets. It returns the selection in the resulting document. Use fresh queries after editing because structural operations rebuild the document and its IDs. The `source` getter then describes the new committed package.
+
+```js
+const paragraph = doc.query.paragraphs().first();
+let selection = {
+  start: { paragraphId: paragraph.id, offset: 0 },
+  end: { paragraphId: paragraph.id, offset: paragraph.text.length }
+};
+selection = await doc.edit({ kind: "format", selection, formatting: { bold: true, fontSize: 18 } });
+selection = await doc.edit({ kind: "replace", selection, text: "First paragraph\nSecond paragraph" });
+await doc.edit({ kind: "align", selection, alignment: "center" });
+const bytes = await doc.save();
+```
+
+Character formatting supports `bold`, `italic`, `underline`, `strike`, `fontSize` in points, `fontFamily`, and `color` as `#RRGGBB`. Values change direct formatting on the selected text while preserving the other authored properties. `run.formatting` exposes the common effective character properties for controls; `paragraph.alignment` exposes left, center, right or justified alignment. These convenience properties describe ordinary Latin text; they do not replace the full semantic typography model for script-specific inspection.
+
+A replacement with a collapsed selection inserts text. Newlines split paragraphs; set `paragraphBreaks: false` for line breaks within a paragraph. Replacing a selection across adjacent paragraphs joins their surviving prefix and suffix. Empty text deletes the selection. New text inherits the starting run's formatting unless the operation includes `formatting`. Split paragraphs inherit the starting paragraph's properties. The first paragraph's properties win when joining.
+
+Rich editing supports ordinary text paragraphs, including empty paragraphs and paragraphs in table cells and secondary stories. Operations affecting paragraphs with fields, links, controls, drawings, comments, bookmarks, tracked revisions or unsupported children reject atomically. Splitting or joining section boundaries and joining across cells or stories also reject. Such content remains preserved elsewhere in the document. The narrower `update()` operation continues to support safe text replacement within unbound controls.
+
+Node and browser documents expose `edit`; server documents forward the same operation. Parsing, semantic construction and browser layout finish before publication, so cancellation or failure leaves the previous document usable. This first implementation rebuilds the document for structural edits. Browser resources stay with the document lifetime, and the sample keeps undo history as document snapshots. Large documents need further editing-performance work before this can serve as a general-purpose editor.
+
+## Run the inline browser editor sample
+
+From the source workspace, run `npm run build` and `npm run example:editor`, then open `http://127.0.0.1:5190`. The sample opens its included Word document and accepts local DOCX files. Click directly on a rendered page to type, drag to select text, and use the toolbar to change formatting. Enter splits paragraphs; Backspace at a paragraph's start joins it to the previous paragraph. Shift+Enter inserts a line break. The sample also supports keyboard selection, copy/cut, plain-text paste, undo/redo and Word download. Files remain in the browser.
+
+The sample is in `examples/browser-editor/`. It consumes only exported SDK and Canvas APIs. Canvas `createDocument` accepts a native textarea through `viewOptions.input`, plus an `onSelectionChange` callback in the same options. The view positions this input at the published caret, handles selection using layout geometry, and exposes `selection` and `setSelection`. The application handles input events and submits `doc.edit()` operations. Text, line wrapping and pagination remain rendered by OnoDocs.
+
+Run `npm run validate:editor` for the browser editing journey. The sample currently uses the workspace build; it requires the new editing APIs and does not work against the earlier published package.
 
 ## Render and attach ordinary DOM
 

package/SDK.md

@@ -60,7 +60,69 @@ Batch range offsets refer to the original paragraph text. Empty ranges insert te
 
 Browser updates rebuild layout and refresh mounted views. Query, semantic, layout, page and geometry values obtained earlier remain snapshots; read them again after updating. Application attachments are removed during refresh and can be reattached using fresh geometry. Updates run in submission order and accept `{ signal }` for cancellation. The original `source` is unchanged.
 
-Node inspection exposes the same update method. For server rendering, inspect the input with the default entry point to select elements or ranges, then pass those updates to the server document before `renderPage` or `pdf`. Exports reflect the updated text. Saving an updated DOCX, structural editing, and field recalculation are not supported.
+Node inspection exposes the same update method. For server rendering, inspect the input with the default entry point to select elements or ranges, then pass those updates to the server document before `renderPage`, `pdf`, or `save`. Exports reflect the updated text.
+
+## Save an edited Word document
+
+`save()` returns DOCX bytes in Node, the browser, and server rendering. Saving without edits returns the original file bytes. Text edits preserve surrounding run formatting and unedited package content. Saving and updating run in submission order. Both accept `{ signal }`; cancellation leaves the committed document available. Call `dispose()` when finished, including for Node documents, to release the preserved source package.
+
+```js
+import { readFile, writeFile } from "node:fs/promises";
+import { openDocument } from "@onodocs/sdk";
+
+const doc = await openDocument(await readFile("template.docx"));
+try {
+  await doc.update({
+    target: doc.query.contentControls().where({ tag: "customer" }).one(),
+    text: "Willow Design"
+  });
+  await writeFile("completed.docx", await doc.save());
+} finally {
+  doc.dispose();
+}
+```
+
+In a browser, create a Blob from the returned bytes with type `application/vnd.openxmlformats-officedocument.wordprocessingml.document`. In a combined deployment, serve `await doc.save()` from an application-owned download endpoint with that content type and a `.docx` filename. The backend processing document owns saving; a Canvas-only frontend does not contain the original Word package.
+
+The SDK package includes a complete command-line example. After installing it, run `node node_modules/@onodocs/sdk/examples/fill-template.mjs template.docx completed.docx customer "Willow Design"`. Set `ONODOCS_LICENSE_KEY` for trial or commercial use. The source workspace keeps the same example at `examples/fill-template.mjs`.
+
+The initial editing profile covers ordinary text and unbound text or rich-text content controls within one paragraph, including supported tables, headers, footers and notes. Edits inside bound or content-locked controls, temporary or specialized controls, fields, revisions, alternate-content branches, and source runs with generated or unsupported content are rejected before publication. Plain-text controls that disallow multiple lines reject newlines. Filling an unbound text control clears its placeholder-display flag. Edits elsewhere preserve these constructs. `DocumentSaveError.reason` identifies source-writing restrictions; existing semantic target errors remain `RangeError`.
+
+Signed packages, enforced document protection, enabled change tracking, macro-enabled documents and templates can be saved unchanged, but editing them is not supported. Field recalculation and revision authoring are not included. Field caches remain as imported, and saved bookmark/comment markers retain their original run boundaries. Original authored formatting is preserved independently of rendering compatibility decisions.
+
+Evaluation exports contain the full Word document without adding a Word watermark. The existing non-production evaluation terms apply; rendered evaluation output continues to include its watermark.
+
+## Edit formatting and paragraphs
+
+`edit()` accepts a logical selection with paragraph IDs and UTF-16 offsets. It returns the selection in the resulting document. Use fresh queries after editing because structural operations rebuild the document and its IDs. The `source` getter then describes the new committed package.
+
+```js
+const paragraph = doc.query.paragraphs().first();
+let selection = {
+  start: { paragraphId: paragraph.id, offset: 0 },
+  end: { paragraphId: paragraph.id, offset: paragraph.text.length }
+};
+selection = await doc.edit({ kind: "format", selection, formatting: { bold: true, fontSize: 18 } });
+selection = await doc.edit({ kind: "replace", selection, text: "First paragraph\nSecond paragraph" });
+await doc.edit({ kind: "align", selection, alignment: "center" });
+const bytes = await doc.save();
+```
+
+Character formatting supports `bold`, `italic`, `underline`, `strike`, `fontSize` in points, `fontFamily`, and `color` as `#RRGGBB`. Values change direct formatting on the selected text while preserving the other authored properties. `run.formatting` exposes the common effective character properties for controls; `paragraph.alignment` exposes left, center, right or justified alignment. These convenience properties describe ordinary Latin text; they do not replace the full semantic typography model for script-specific inspection.
+
+A replacement with a collapsed selection inserts text. Newlines split paragraphs; set `paragraphBreaks: false` for line breaks within a paragraph. Replacing a selection across adjacent paragraphs joins their surviving prefix and suffix. Empty text deletes the selection. New text inherits the starting run's formatting unless the operation includes `formatting`. Split paragraphs inherit the starting paragraph's properties. The first paragraph's properties win when joining.
+
+Rich editing supports ordinary text paragraphs, including empty paragraphs and paragraphs in table cells and secondary stories. Operations affecting paragraphs with fields, links, controls, drawings, comments, bookmarks, tracked revisions or unsupported children reject atomically. Splitting or joining section boundaries and joining across cells or stories also reject. Such content remains preserved elsewhere in the document. The narrower `update()` operation continues to support safe text replacement within unbound controls.
+
+Node and browser documents expose `edit`; server documents forward the same operation. Parsing, semantic construction and browser layout finish before publication, so cancellation or failure leaves the previous document usable. This first implementation rebuilds the document for structural edits. Browser resources stay with the document lifetime, and the sample keeps undo history as document snapshots. Large documents need further editing-performance work before this can serve as a general-purpose editor.
+
+## Run the inline browser editor sample
+
+From the source workspace, run `npm run build` and `npm run example:editor`, then open `http://127.0.0.1:5190`. The sample opens its included Word document and accepts local DOCX files. Click directly on a rendered page to type, drag to select text, and use the toolbar to change formatting. Enter splits paragraphs; Backspace at a paragraph's start joins it to the previous paragraph. Shift+Enter inserts a line break. The sample also supports keyboard selection, copy/cut, plain-text paste, undo/redo and Word download. Files remain in the browser.
+
+The sample is in `examples/browser-editor/`. It consumes only exported SDK and Canvas APIs. Canvas `createDocument` accepts a native textarea through `viewOptions.input`, plus an `onSelectionChange` callback in the same options. The view positions this input at the published caret, handles selection using layout geometry, and exposes `selection` and `setSelection`. The application handles input events and submits `doc.edit()` operations. Text, line wrapping and pagination remain rendered by OnoDocs.
+
+Run `npm run validate:editor` for the browser editing journey. The sample currently uses the workspace build; it requires the new editing APIs and does not work against the earlier published package.
 
 ## Render and attach ordinary DOM
 

package/index.js

@@ -1578,7 +1578,7 @@ __name(fillExactSectionColumnSeparator, "fillExactSectionColumnSeparator");
 
 // packages/canvas/src/text-selection.ts
 var nextView = 0;
-function mountTextSelection(pageText, viewport, shells, pageBounds, nearby, signal) {
+function mountTextSelection(pageText, viewport, shells, pageBounds, nearby, signal, input, onSelectionChange) {
   const document2 = viewport.ownerDocument;
   const window = document2.defaultView;
   const svg = "http://www.w3.org/2000/svg";
@@ -1607,7 +1607,7 @@ function mountTextSelection(pageText, viewport, shells, pageBounds, nearby, sign
     for (const caret of value.carets) {
       const offset = offsets[caret.scalarOffset - value.scalarStart];
       if (offset === void 0) continue;
-      const stop = { line, offset: length + offset, x: caret.x, index: stops.length };
+      const stop = { line, offset: length + offset, x: caret.x, index: stops.length, ...caret.paragraphOffset === void 0 ? {} : { position: { paragraphId: value.paragraphId, offset: caret.paragraphOffset } } };
       line.stops.push(stop);
       stops.push(stop);
     }
@@ -1639,6 +1639,10 @@ function mountTextSelection(pageText, viewport, shells, pageBounds, nearby, sign
   let menu;
   viewport.tabIndex = 0;
   viewport.style.userSelect = "none";
+  if (input) {
+    viewport.style.position = "relative";
+    viewport.append(input);
+  }
   for (const shell of shells) shell.style.cursor = "text";
   function paint() {
     for (const [index, layer] of layers) {
@@ -1646,7 +1650,13 @@ function mountTextSelection(pageText, viewport, shells, pageBounds, nearby, sign
       layer.replaceChildren();
       if (!nearby.has(index)) layers.delete(index);
     }
-    if (!anchor || !focus || document2.activeElement !== viewport && !menu?.contains(document2.activeElement)) return;
+    if (!anchor || !focus || !input && document2.activeElement !== viewport && !menu?.contains(document2.activeElement)) return;
+    if (input) {
+      const shell = shells[focus.line.item.pageIndex], bounds = shell.getBoundingClientRect(), origin = viewport.getBoundingClientRect();
+      const point = focus.line.transform.transformPoint({ x: focus.x, y: focus.line.item.selection.top });
+      const scale = bounds.width / pageBounds[focus.line.item.pageIndex].width;
+      Object.assign(input.style, { position: "absolute", left: `${bounds.left - origin.left + point.x * scale}px`, top: `${bounds.top - origin.top + point.y * scale}px`, height: `${focus.line.item.selection.height * scale}px` });
+    }
     const start = Math.min(anchor.offset, focus.offset), end = Math.max(anchor.offset, focus.offset);
     for (const index of nearby) for (const line of pages[index] ?? []) {
       let rectangle2 = function(x, width, caret = false) {
@@ -1707,7 +1717,7 @@ function mountTextSelection(pageText, viewport, shells, pageBounds, nearby, sign
   __name(paint, "paint");
   function nearest(clientX, clientY) {
     if (!logical.length) return;
-    let result, best = Infinity;
+    let result, bestY = Infinity, bestX = Infinity;
     let first = 0, last = shells.length - 1;
     while (first < last) {
       const middle = first + last >>> 1;
@@ -1732,9 +1742,9 @@ function mountTextSelection(pageText, viewport, shells, pageBounds, nearby, sign
         const dy = Math.max(value.top - y, 0, y - value.top - value.height) * box.height / height;
         for (const stop of line.stops) {
           const dx = Math.abs(stop.x - x) * box.width / width;
-          const distance = dy * dy * 16 + dx * dx;
-          if (distance < best) {
-            best = distance;
+          if (dy < bestY || dy === bestY && dx < bestX) {
+            bestY = dy;
+            bestX = dx;
             result = stop;
           }
         }
@@ -1748,6 +1758,8 @@ function mountTextSelection(pageText, viewport, shells, pageBounds, nearby, sign
     focus = stop;
     if (!extend || !anchor) anchor = stop;
     paint();
+    onSelectionChange?.(currentSelection());
+    if (input && document2.activeElement === viewport) input.focus({ preventScroll: true });
     if (scroll) {
       const shell = shells[stop.line.item.pageIndex];
       const point = stop.line.transform.transformPoint({ x: stop.x, y: stop.line.item.selection.top });
@@ -1788,13 +1800,23 @@ function mountTextSelection(pageText, viewport, shells, pageBounds, nearby, sign
     pointerPosition = { x: event.clientX, y: event.clientY };
     select(nearest(event.clientX, event.clientY), true);
   }, { signal });
+  viewport.addEventListener("dblclick", (event) => {
+    if (event.target.closest("button,input,textarea,select,a,[data-onodocs-attachment]")) return;
+    const stop = nearest(event.clientX, event.clientY);
+    if (!stop) return;
+    const segment = [...new Intl.Segmenter(void 0, { granularity: "word" }).segment(text)].find((value) => stop.offset >= value.index && stop.offset < value.index + value.segment.length);
+    if (!segment) return;
+    event.preventDefault();
+    anchor = logical.find((value) => value.offset >= segment.index);
+    select(logical.find((value) => value.offset >= segment.index + segment.segment.length), true);
+  }, { signal });
   for (const type of ["pointerup", "pointercancel", "lostpointercapture"]) viewport.addEventListener(type, (event) => {
     if (event.pointerId !== pointer) return;
     pointer = void 0;
     window.cancelAnimationFrame(frame);
   }, { signal });
   viewport.addEventListener("keydown", (event) => {
-    if (event.target !== viewport || !logical.length) return;
+    if (event.target !== viewport && event.target !== input || !logical.length || event.isComposing) return;
     const command = event.ctrlKey || event.metaKey;
     if (command && event.key.toLowerCase() === "a") {
       event.preventDefault();
@@ -1813,7 +1835,11 @@ function mountTextSelection(pageText, viewport, shells, pageBounds, nearby, sign
     else if (event.key === "ArrowLeft" || event.key === "ArrowRight") {
       const delta = event.key === "ArrowLeft" ? -1 : 1;
       if (!event.shiftKey && anchor.offset !== focus.offset) next = delta < 0 ? anchor.offset < focus.offset ? anchor : focus : anchor.offset > focus.offset ? anchor : focus;
-      else {
+      else if (command) {
+        const words = [...new Intl.Segmenter(void 0, { granularity: "word" }).segment(text)].filter((value) => value.isWordLike);
+        const offset = delta < 0 ? words.filter((value) => value.index < focus.offset).at(-1)?.index ?? 0 : words.find((value) => value.index > focus.offset)?.index ?? text.length;
+        next = logical.find((value) => value.offset >= offset) ?? logical.at(-1);
+      } else {
         let index = logicalIndex.get(focus) + delta;
         while (logical[index]?.offset === focus.offset) index += delta;
         next = logical[Math.max(0, Math.min(logical.length - 1, index))];
@@ -1830,7 +1856,7 @@ function mountTextSelection(pageText, viewport, shells, pageBounds, nearby, sign
     select(next, event.shiftKey, true);
   }, { signal });
   document2.addEventListener("copy", (event) => {
-    if (document2.activeElement !== viewport && !menu?.contains(document2.activeElement) || !focus || anchor.offset === focus.offset) return;
+    if (document2.activeElement !== viewport && document2.activeElement !== input && !menu?.contains(document2.activeElement) || !focus || anchor.offset === focus.offset) return;
     event.clipboardData?.setData("text/plain", selectedText());
     event.preventDefault();
   }, { signal });
@@ -1918,7 +1944,25 @@ function mountTextSelection(pageText, viewport, shells, pageBounds, nearby, sign
     window.cancelAnimationFrame(frame);
     for (const layer of layers.values()) layer.remove();
   }, { once: true });
-  return { paint };
+  function currentSelection() {
+    if (!anchor?.position || !focus?.position) return;
+    return anchor.offset <= focus.offset ? { start: anchor.position, end: focus.position } : { start: focus.position, end: anchor.position };
+  }
+  __name(currentSelection, "currentSelection");
+  const byParagraph = /* @__PURE__ */ new Map();
+  for (const stop of logical) if (stop.position) {
+    let offsets = byParagraph.get(stop.position.paragraphId);
+    if (!offsets) byParagraph.set(stop.position.paragraphId, offsets = /* @__PURE__ */ new Map());
+    offsets.set(stop.position.offset, stop);
+  }
+  return { paint, get selection() {
+    return currentSelection();
+  }, setSelection(value) {
+    const start = byParagraph.get(value.start.paragraphId)?.get(value.start.offset), end = byParagraph.get(value.end.paragraphId)?.get(value.end.offset);
+    if (!start || !end) return;
+    anchor = start;
+    select(end, true, true);
+  } };
 }
 __name(mountTextSelection, "mountTextSelection");
 
@@ -1965,10 +2009,10 @@ function mountDocument(document2, container, options = {}, onDispose) {
   let selection;
   let selectionLifetime;
   function prepareSelection(event) {
-    if (event.target.closest("[data-onodocs-attachment]")) return;
+    if (event?.target?.closest("[data-onodocs-attachment]")) return;
     if (selection) return;
     selectionLifetime = new AbortController();
-    selection = mountTextSelection(document2.pages.flatMap((page) => page.interaction.text), element, shells.map((entry) => entry.shell), document2.pages.map((page) => page.size), nearby, AbortSignal.any([lifetime.signal, selectionLifetime.signal]));
+    selection = mountTextSelection(document2.pages.flatMap((page) => page.interaction.text), element, shells.map((entry) => entry.shell), document2.pages.map((page) => page.size), nearby, AbortSignal.any([lifetime.signal, selectionLifetime.signal]), options.input, options.onSelectionChange);
   }
   __name(prepareSelection, "prepareSelection");
   for (const type of ["pointerdown", "keydown", "contextmenu", "focus"]) element.addEventListener(type, prepareSelection, { capture: true, signal: lifetime.signal });
@@ -2041,6 +2085,14 @@ function mountDocument(document2, container, options = {}, onDispose) {
   }
   const view = {
     element,
+    get selection() {
+      return selection?.selection;
+    },
+    setSelection(value) {
+      checkOpen();
+      prepareSelection();
+      selection.setSelection(value);
+    },
     get disposed() {
       return disposed;
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onodocs/canvas",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "private": false,
   "description": "OnoDocs canvas viewer, selection and HTML attachments for prepared Word document pages.",
   "homepage": "https://onodocs.com/developers/",
@@ -15,7 +15,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "onodocsReleaseDate": "2026-10-07",
+  "onodocsReleaseDate": "2026-10-08",
   "onodocsEnvironment": "live",
   "type": "module",
   "sideEffects": false,
@@ -40,5 +40,5 @@
     "type": "git",
     "url": "https://github.com/onodocs/onodocs.git"
   },
-  "gitHead": "69453bc7ca1f06f5ee022dd905765bf1d513e53a"
+  "gitHead": "cf082bcfda5fc7581332b4251fa27c39a9a66ec7"
 }

package/types/canvas/presentation.d.ts

@@ -1,11 +1,13 @@
 /** Spec: pipeline.semantic.document-update */
 /** Spec: pipeline.sdk.presentation */
-import type { DocumentFragment, DocumentHit, DocumentPoint } from "../render-api/index.js";
+import type { DocumentFragment, DocumentHit, DocumentPoint, DocumentSelection } from "../render-api/index.js";
 import type { DocumentPage, PageSize } from "./index.js";
 export interface ViewOptions {
     readonly zoom?: number | "fit-width";
     readonly gap?: number;
     readonly title?: string;
+    readonly input?: HTMLTextAreaElement;
+    readonly onSelectionChange?: (selection: DocumentSelection | undefined) => void;
 }
 export interface DocumentAttachment {
     readonly element: HTMLElement;
@@ -42,6 +44,8 @@ export interface DocumentView {
         point: DocumentPoint;
     }> | undefined;
     hitTest(point: DocumentPoint): DocumentHit | undefined;
+    readonly selection: DocumentSelection | undefined;
+    setSelection(selection: DocumentSelection): void;
     scrollTo(anchor: ViewAnchor, options?: ScrollIntoViewOptions): boolean;
     attach(element: HTMLElement, options: AttachmentOptions): DocumentAttachment;
     dispose(): void;

package/types/canvas/text-selection.d.ts

@@ -1,7 +1,9 @@
-import type { PageTextLine } from "../render-api/index.js";
+import type { DocumentSelection, PageTextLine } from "../render-api/index.js";
 import type { DocumentPage } from "./index.js";
 /** Spec: pipeline.sdk.presentation */
-export declare function mountTextSelection(pageText: readonly PageTextLine[], viewport: HTMLElement, shells: readonly HTMLElement[], pageBounds: readonly DocumentPage["size"][], nearby: ReadonlySet<number>, signal: AbortSignal): {
+export declare function mountTextSelection(pageText: readonly PageTextLine[], viewport: HTMLElement, shells: readonly HTMLElement[], pageBounds: readonly DocumentPage["size"][], nearby: ReadonlySet<number>, signal: AbortSignal, input?: HTMLTextAreaElement, onSelectionChange?: (selection: DocumentSelection | undefined) => void): {
     paint: () => void;
+    readonly selection: DocumentSelection | undefined;
+    setSelection(value: DocumentSelection): void;
 };
 //# sourceMappingURL=text-selection.d.ts.map

package/types/foundation/page-interaction.d.ts

@@ -3,6 +3,14 @@ export interface DocumentPoint {
     readonly x: number;
     readonly y: number;
 }
+export interface ParagraphPosition {
+    readonly paragraphId: string;
+    readonly offset: number;
+}
+export interface DocumentSelection {
+    readonly start: ParagraphPosition;
+    readonly end: ParagraphPosition;
+}
 export interface PageRectangle extends DocumentPoint {
     readonly width: number;
     readonly height: number;
@@ -54,6 +62,7 @@ export interface PageTextLine {
         carets: readonly Readonly<{
             scalarOffset: number;
             x: number;
+            paragraphOffset?: number;
         }>[];
     }>;
 }

package/types/render-api/index.d.ts

@@ -1,4 +1,4 @@
 export * from "./page-display-list.js";
 export * from "./page-source.js";
-export type { DocumentFragment, DocumentHit, DocumentPoint, PageTextLine, PageInteraction, FontFaceResource, ImageResourceData } from "../foundation/index.js";
+export type { DocumentFragment, DocumentHit, DocumentPoint, DocumentSelection, ParagraphPosition, PageTextLine, PageInteraction, FontFaceResource, ImageResourceData } from "../foundation/index.js";
 //# sourceMappingURL=index.d.ts.map