nuvra 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eshonqul
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,163 @@
+# nuvra
+
+Word-style document editor for Vue 3. A real page view with paper sizes and margins, a lighter web view for
+forms, tables, images, lists, find & replace, HTML source mode, printing and export to HTML or Word (`.doc`).
+
+- No editor framework underneath: its own small editing engine with a sanitizing schema.
+- Pagination in the page view (A4, A5, Letter, …, portrait or landscape).
+- Tables with merge / split, images with resize and alignment, task lists, links, colors, fonts.
+- Undo / redo, keyboard shortcuts that work with non-Latin keyboard layouts, Markdown-like input rules.
+- Built on [Element Plus](https://element-plus.org) controls and [Lucide](https://lucide.dev) icons.
+
+## Installation
+
+```sh
+pnpm add nuvra element-plus
+# or
+npm install nuvra element-plus
+```
+
+`vue` (3.5+) and `element-plus` (2.9+) are peer dependencies.
+
+Import the styles once, next to the Element Plus styles:
+
+```ts
+import 'element-plus/dist/index.css';
+import 'nuvra/style.css';
+```
+
+## Usage
+
+### Document editor
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { DocumentEditor, type PageSettings, createPageSettings } from 'nuvra';
+
+const html = ref('');
+const page = ref<PageSettings>(createPageSettings());
+</script>
+
+<template>
+  <DocumentEditor v-model="html" v-model:page="page" height="100%" title="Contract" />
+</template>
+```
+
+### Form field
+
+`Editor` is the same editor in the web view, growing with its content between `minHeight` and `maxHeight`:
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Editor } from 'nuvra';
+
+const description = ref('');
+</script>
+
+<template>
+  <Editor v-model="description" placeholder="Description" :max-length="2000" />
+</template>
+```
+
+### Image upload
+
+Without an upload handler images are embedded as data URLs. Pass `uploadImage` to store them on your server:
+
+```ts
+import type { DocumentImageUploadHandler } from 'nuvra';
+
+const uploadImage: DocumentImageUploadHandler = async file => {
+  const body = new FormData();
+  body.append('file', file);
+  const response = await fetch('/api/files', { method: 'POST', body });
+  return (await response.json()).url;
+};
+```
+
+## API
+
+### `DocumentEditor` props
+
+| Prop              | Type                                    | Default  | Description                                                              |
+| ----------------- | --------------------------------------- | -------- | ------------------------------------------------------------------------ |
+| `v-model`         | `string`                                | `''`     | Document HTML; an empty document is an empty string.                     |
+| `v-model:page`    | `PageSettings`                          | A4       | Paper size, orientation and margins.                                     |
+| `autofocus`       | `boolean`                               | `false`  | Places the caret at the end of the document once ready.                  |
+| `canvasPadding`   | `number \| string`                      | `50`     | Gray space around the page or web sheet.                                 |
+| `defaultViewMode` | `'page' \| 'web'`                       | `'page'` | View shown first.                                                        |
+| `disabled`        | `boolean`                               | `false`  | Read-only document, disabled controls.                                   |
+| `height`          | `number \| string`                      | `760`    | Height of the editor, or `'auto'` to grow between `minHeight`/`maxHeight`. |
+| `minHeight`       | `number \| string`                      | `240`    | Smallest height of an auto-height editor.                                |
+| `maxHeight`       | `number \| string`                      | `600`    | Largest height of an auto-height editor.                                 |
+| `maxImageSizeMb`  | `number`                                | `10`     | Largest accepted image file.                                             |
+| `maxLength`       | `number`                                | `0`      | Character limit; `0` means unlimited.                                    |
+| `placeholder`     | `string`                                | `''`     | Text shown while the document is empty.                                  |
+| `title`           | `string`                                | `''`     | Print title and exported file name.                                      |
+| `uploadImage`     | `(file: File) => Promise<string>`       | —        | Uploads an image and resolves with its URL.                              |
+
+`Editor` accepts the same props except `v-model:page`, `defaultViewMode`, `height` and `title`.
+
+Numbers are pixels; strings are used as CSS lengths (`'100%'`, `'50vh'`).
+
+### Events
+
+| Event         | Payload          | Description                                   |
+| ------------- | ---------------- | --------------------------------------------- |
+| `focus`       | —                | The document received focus.                  |
+| `blur`        | —                | The document lost focus; the model is up to date. |
+| `uploadError` | `error: unknown` | An image was rejected or its upload failed.   |
+
+### Exposed methods (`DocumentEditor` ref)
+
+| Method         | Description                                                    |
+| -------------- | -------------------------------------------------------------- |
+| `focus()`      | Moves keyboard focus into the document.                        |
+| `getHTML()`    | Returns the document HTML, including edits not yet in the model. |
+| `print()`      | Opens the browser print dialog.                                |
+| `exportHtml()` | Downloads the document as an HTML page.                        |
+| `exportWord()` | Downloads the document as a Word-compatible `.doc` file.       |
+| `engine`       | The editing engine, for advanced integrations.                 |
+
+### Keyboard shortcuts
+
+`Ctrl/⌘+B`, `I`, `U` — bold, italic, underline · `Ctrl/⌘+Z`, `Ctrl/⌘+Shift+Z` — undo, redo ·
+`Ctrl/⌘+F` — find · `Ctrl/⌘+H` — replace · `Ctrl/⌘+K` — link · `Ctrl/⌘+P` — print.
+
+## Translations
+
+Built-in labels are in Uzbek. Every label has a key such as `editor.bold`; the full list with default texts is
+exported as `editorMessages`. Register a translator once, before the app mounts. Returning `undefined` keeps the
+built-in text for that key.
+
+```ts
+import { setEditorTranslator } from 'nuvra';
+
+const en: Record<string, string> = {
+  'editor.bold': 'Bold',
+  'editor.status.words': '{count} words'
+};
+
+setEditorTranslator((key, named) =>
+  en[key]?.replace(/\{(\w+)\}/g, (_, name) => String(named?.[name] ?? ''))
+);
+```
+
+With `vue-i18n`, labels follow the active locale:
+
+```ts
+import { setEditorTranslator } from 'nuvra';
+import { i18n } from './i18n';
+
+setEditorTranslator((key, named) => (i18n.global.te(key) ? i18n.global.t(key, named ?? {}) : undefined));
+```
+
+## Theming
+
+The editor uses Element Plus CSS variables (`--el-color-primary`, `--el-border-color`, `--el-bg-color`, …), so it
+follows your Element Plus theme and dark mode.
+
+## License
+
+[MIT](./LICENSE)

package/dist/components/document-editor.vue.d.ts

@@ -0,0 +1,82 @@
+import { DocumentEngine } from '../core/engine/engine';
+import { type DocumentViewMode, type PageSettings } from '../core/page';
+import type { DocumentImageUploadHandler } from '../core/types';
+import '../styles/document-content.css';
+import '../styles/editor-ui.css';
+/** A CSS length: numbers are pixels, strings are used as written (for example, `'100%'` or `'auto'`). */
+type CssSize = number | string;
+interface Props {
+    /** Places the caret at the end of the document as soon as the editor is ready. */
+    autofocus?: boolean;
+    /** Gray space around the page or web sheet that separates the document from the editor frame. */
+    canvasPadding?: CssSize;
+    /** View shown first; form fields use the lighter web view. */
+    defaultViewMode?: DocumentViewMode;
+    /** Makes the document read-only and disables every editing control. */
+    disabled?: boolean;
+    /** Height of the whole editor, or `'auto'` to grow with the content between `minHeight` and `maxHeight`. */
+    height?: CssSize;
+    /** Largest height of an auto-height editor; longer documents scroll inside it. */
+    maxHeight?: CssSize;
+    /** Largest accepted image file, in megabytes. */
+    maxImageSizeMb?: number;
+    /** Largest number of characters the document may contain; `0` means unlimited. */
+    maxLength?: number;
+    /** Smallest height of an auto-height editor. */
+    minHeight?: CssSize;
+    /** Text shown while the document is empty; falls back to the translated default placeholder. */
+    placeholder?: string;
+    /** Used as the print title and the exported file name. */
+    title?: string;
+    /** Uploads an inserted image and resolves with its URL; without it images are embedded as data URLs. */
+    uploadImage?: DocumentImageUploadHandler;
+}
+type __VLS_Props = Props;
+type __VLS_ModelProps = {
+    /** Document HTML. An empty document is written as an empty string; typing updates it after a short delay. */
+    modelValue?: string;
+    /** Paper size, orientation, and margins used by the page view, printing, and export. */
+    'page'?: PageSettings;
+};
+type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
+declare const __VLS_export: import("vue").DefineComponent<__VLS_PublicProps, {
+    /** The editing engine, for advanced integrations. */
+    engine: import("vue").ShallowRef<DocumentEngine | null, DocumentEngine | null>;
+    /** Downloads the document as an HTML page. */
+    exportHtml: () => Promise<void>;
+    /** Downloads the document as a Word-compatible file. */
+    exportWord: () => Promise<void>;
+    /** Moves keyboard focus into the document. */
+    focus: () => void | undefined;
+    /** Returns the document HTML, including edits not yet written to the model. */
+    getHTML: () => string;
+    /** Opens the print dialog. */
+    print: () => Promise<void>;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    focus: () => any;
+    blur: () => any;
+    "update:modelValue": (value: string) => any;
+    "update:page": (value: PageSettings) => any;
+    uploadError: (error: unknown) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    onFocus?: (() => any) | undefined;
+    onBlur?: (() => any) | undefined;
+    "onUpdate:modelValue"?: ((value: string) => any) | undefined;
+    "onUpdate:page"?: ((value: PageSettings) => any) | undefined;
+    onUploadError?: ((error: unknown) => any) | undefined;
+}>, {
+    title: string;
+    height: CssSize;
+    disabled: boolean;
+    placeholder: string;
+    autofocus: boolean;
+    minHeight: CssSize;
+    maxLength: number;
+    maxHeight: CssSize;
+    canvasPadding: CssSize;
+    defaultViewMode: DocumentViewMode;
+    maxImageSizeMb: number;
+    uploadImage: DocumentImageUploadHandler;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/editor-bubble-menus.vue.d.ts

@@ -0,0 +1,14 @@
+import type { DocumentEngine } from '../core/engine/engine';
+interface Props {
+    /** Engine whose selection decides which menu is shown. */
+    engine: DocumentEngine;
+    /** Canvas scroll container; menus follow its scrolling and hide when their target leaves it. */
+    scrollTarget: HTMLElement;
+}
+declare const __VLS_export: import("vue").DefineComponent<Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    editLink: () => any;
+}, string, import("vue").PublicProps, Readonly<Props> & Readonly<{
+    onEditLink?: (() => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/editor-canvas.vue.d.ts

@@ -0,0 +1,30 @@
+import type { DocumentEngine } from '../core/engine/engine';
+import type { DocumentViewMode, PageMetrics } from '../core/page';
+interface Props {
+    /** Grow with the content between the editor's min and max height instead of filling a fixed height. */
+    autoHeight: boolean;
+    /** Engine working on the editable element; `null` until the parent has created it. */
+    engine: DocumentEngine | null;
+    /** Page size and margins in pixels. */
+    metrics: PageMetrics;
+    /** Number of sheets drawn behind the content in page view. */
+    pageCount: number;
+    /** Paginated sheets or a single web sheet. */
+    viewMode: DocumentViewMode;
+    /** Zoom in percent. */
+    zoom: number;
+}
+declare const __VLS_export: import("vue").DefineComponent<Props, {
+    /** The editable element the engine is created on. */
+    contentElement: import("vue").Ref<HTMLElement | undefined, HTMLElement | undefined>;
+    /** Zoom percentage that makes the page fill the canvas width. */
+    getFitWidthZoom: () => number;
+    /** The scroll container, followed by floating menus. */
+    scrollElement: import("vue").Ref<HTMLElement | undefined, HTMLElement | undefined>;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    resize: (contentWidth: number) => any;
+}, string, import("vue").PublicProps, Readonly<Props> & Readonly<{
+    onResize?: ((contentWidth: number) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/editor-color-picker.vue.d.ts

@@ -0,0 +1,15 @@
+interface Props {
+    /** Colour applied under the caret, used to mark the selected swatch. */
+    current: string;
+    /** Disables both parts of the button. */
+    disabled: boolean;
+    /** Whether the picker sets the text colour or the highlight colour. */
+    mode: 'text' | 'highlight';
+}
+declare const __VLS_export: import("vue").DefineComponent<Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    select: (color: string | null) => any;
+}, string, import("vue").PublicProps, Readonly<Props> & Readonly<{
+    onSelect?: ((color: string | null) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/editor-find-bar.vue.d.ts

@@ -0,0 +1,24 @@
+import type { DocumentEngine } from '../core/engine/engine';
+interface Props {
+    /** Engine whose document is searched. */
+    engine: DocumentEngine;
+    /** Hides the replacement row when the document cannot be edited. */
+    readonly: boolean | undefined;
+}
+type __VLS_Props = Props;
+type __VLS_ModelProps = {
+    /** Whether the replacement row is expanded; kept by the parent so Ctrl+H can open it directly. */
+    'replace'?: boolean;
+};
+type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
+declare const __VLS_export: import("vue").DefineComponent<__VLS_PublicProps, {
+    focus: () => void;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    close: () => any;
+    "update:replace": (value: boolean) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    onClose?: (() => any) | undefined;
+    "onUpdate:replace"?: ((value: boolean) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/editor-object-overlay.vue.d.ts

@@ -0,0 +1,10 @@
+import type { DocumentEngine } from '../core/engine/engine';
+interface Props {
+    /** Engine whose selected image and tables are edited. */
+    engine: DocumentEngine;
+    /** Zoom in percent, needed to convert pointer movement into document pixels. */
+    zoom: number;
+}
+declare const __VLS_export: import("vue").DefineComponent<Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/editor-page-setup.vue.d.ts

@@ -0,0 +1,12 @@
+import { type PageSettings } from '../core/page';
+interface Props {
+    /** Settings currently applied to the document. */
+    page: PageSettings;
+}
+declare const __VLS_export: import("vue").DefineComponent<Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    change: (page: PageSettings) => any;
+}, string, import("vue").PublicProps, Readonly<Props> & Readonly<{
+    onChange?: ((page: PageSettings) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/editor-status-bar.vue.d.ts

@@ -0,0 +1,36 @@
+import { type DocumentViewMode } from '../core/page';
+interface Props {
+    /** Number of characters in the document. */
+    characters: number;
+    /** Page that contains the caret (page view only). */
+    currentPage: number;
+    /** Whether the editor currently covers the screen. */
+    fullscreen: boolean;
+    /** Character limit; 0 means unlimited and shows a plain counter. */
+    maxLength: number | undefined;
+    /** Number of pages the document occupies (page view only). */
+    pageCount: number;
+    /** Number of words in the document. */
+    words: number;
+}
+type __VLS_Props = Props;
+type __VLS_ModelProps = {
+    /** Zoom in percent; every change is snapped to the zoom step and clamped to the allowed range. */
+    'zoom': number;
+    /** Page layout with sheets, or the continuous web layout. */
+    'viewMode': DocumentViewMode;
+};
+type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
+declare const __VLS_export: import("vue").DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    fitWidth: () => any;
+    toggleFullscreen: () => any;
+    "update:zoom": (value: number) => any;
+    "update:viewMode": (value: DocumentViewMode) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    onFitWidth?: (() => any) | undefined;
+    onToggleFullscreen?: (() => any) | undefined;
+    "onUpdate:zoom"?: ((value: number) => any) | undefined;
+    "onUpdate:viewMode"?: ((value: DocumentViewMode) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/editor-table-picker.vue.d.ts

@@ -0,0 +1,16 @@
+/** Table requested by the user. */
+interface TableSelection {
+    /** Number of rows, header row included. */
+    rows: number;
+    /** Number of columns. */
+    cols: number;
+    /** Whether the first row is made of header cells. */
+    withHeaderRow: boolean;
+}
+declare const __VLS_export: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    select: (table: TableSelection) => any;
+}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{
+    onSelect?: ((table: TableSelection) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/editor-toolbar.vue.d.ts

@@ -0,0 +1,38 @@
+import type { DocumentEngine } from '../core/engine/engine';
+import type { PageSettings } from '../core/page';
+import type { DocumentMenuAction } from '../core/types';
+import { type EditorUiState } from '../core/ui-state';
+interface Props {
+    /** Read-only document: every editing control is disabled. */
+    disabled: boolean | undefined;
+    /** Engine that receives the commands. */
+    engine: DocumentEngine;
+    /** Whether the find bar is open, shown as the search button state. */
+    findOpen: boolean;
+    /** Whether the editor is in fullscreen, used for the menu item label. */
+    fullscreen: boolean;
+    /** Current page settings, edited in the page setup popover. */
+    page: PageSettings;
+    /** Whether the HTML source is shown; formatting controls are disabled meanwhile. */
+    sourceMode: boolean;
+    /** Formatting at the caret, used for active states and labels. */
+    state: EditorUiState;
+    /** Whether images are being uploaded, shown on the upload button. */
+    uploading: boolean;
+}
+declare const __VLS_export: import("vue").DefineComponent<Props, {
+    /** Opens the link popover. */
+    openLink: () => void;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    menu: (action: DocumentMenuAction) => any;
+    find: () => any;
+    insertImages: (files: File[]) => any;
+    "update:page": (page: PageSettings) => any;
+}, string, import("vue").PublicProps, Readonly<Props> & Readonly<{
+    onMenu?: ((action: DocumentMenuAction) => any) | undefined;
+    onFind?: (() => any) | undefined;
+    onInsertImages?: ((files: File[]) => any) | undefined;
+    "onUpdate:page"?: ((page: PageSettings) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/core/engine/blocks.d.ts

@@ -0,0 +1,37 @@
+/** Heading element tags. */
+export type HeadingTag = 'H1' | 'H2' | 'H3' | 'H4' | 'H5' | 'H6';
+/** Paragraph alignment; `left` is the default and is stored as no style. */
+export type TextAlign = 'left' | 'center' | 'right' | 'justify';
+/** Paragraph direction; `auto` is stored as no `dir` attribute. */
+export type TextDirection = 'auto' | 'ltr' | 'rtl';
+/** The element whose children are blocks: the document, a quote, a list item body or a table cell. */
+export declare const containerOf: (node: Node, root: HTMLElement) => HTMLElement;
+/** The direct child of `container` that contains `node` (or `node` itself when it is a direct child). */
+export declare const childOf: (container: Node, node: Node) => Node;
+/** Turns every selected text block into a paragraph or heading, keeping its alignment and indentation. */
+export declare const setBlockType: (root: HTMLElement, range: Range, tag: "P" | HeadingTag) => void;
+/** Converts the selected blocks to code blocks, or back to paragraphs when all of them already are. */
+export declare const toggleCodeBlock: (root: HTMLElement, range: Range) => void;
+/**
+ * Unwraps the quotes around the selection when every selected block is quoted; otherwise wraps the selected
+ * blocks, at the level of their closest common container, in a new quote.
+ */
+export declare const toggleBlockquote: (root: HTMLElement, range: Range) => void;
+/** Aligns the selected paragraphs and headings; code blocks keep their alignment. */
+export declare const setTextAlign: (root: HTMLElement, range: Range, align: TextAlign) => void;
+/** Sets the line height of the selected paragraphs and headings, or resets it with `null`. */
+export declare const setLineHeight: (root: HTMLElement, range: Range, lineHeight: string | null) => void;
+/** Sets the writing direction of the selected blocks; `auto` lets each paragraph follow its own text. */
+export declare const setTextDirection: (root: HTMLElement, range: Range, direction: TextDirection) => void;
+/**
+ * Moves the selected paragraphs outside lists by whole indentation steps.
+ * @returns whether any block's indentation changed.
+ */
+export declare const changeIndent: (root: HTMLElement, range: Range, delta: number) => boolean;
+/** Splits a text block at a point; the new right-hand block keeps the tag and paragraph formatting. */
+export declare const splitBlock: (block: HTMLElement, container: Node, offset: number) => HTMLElement;
+/**
+ * Places a block element (rule, page break, image, table) at the caret and returns the text block that should
+ * receive the caret afterwards.
+ */
+export declare const insertBlockAtCaret: (root: HTMLElement, range: Range, element: HTMLElement) => HTMLElement;

package/dist/core/engine/clipboard.d.ts

@@ -0,0 +1,23 @@
+/** The parts of a clipboard or drag payload the editor uses. */
+export interface TransferContent {
+    /** Rich HTML, empty when the source offered none. */
+    html: string;
+    /** Plain text, empty when the source offered none. */
+    text: string;
+    /** Files, e.g. pasted screenshots or dropped images. */
+    files: File[];
+}
+/** Extracts HTML, text and files from a clipboard or drag payload. */
+export declare const readTransfer: (data: DataTransfer | null) => TransferContent;
+/** The image files of a payload. */
+export declare const imageFiles: (content: TransferContent) => File[];
+/** The URL when the plain text is a single web address (`www.` addresses get `https://`), otherwise `null`. */
+export declare const singleUrl: (content: TransferContent) => string | null;
+/** Converts plain text into paragraphs, one per line; a final line break does not add an empty paragraph. */
+export declare const textToFragment: (text: string) => DocumentFragment;
+/** Converts a payload into editor blocks, preferring sanitised HTML over plain text; `null` when it has neither. */
+export declare const transferToFragment: (content: TransferContent) => DocumentFragment | null;
+/** Puts clean HTML and plain text of the selection on a clipboard or drag payload for copy, cut and drag. */
+export declare const writeTransfer: (data: DataTransfer, root: HTMLElement, range: Range) => void;
+/** Collapsed range at the text position under the pointer, used to place dropped content and canvas clicks. */
+export declare const rangeFromPoint: (x: number, y: number) => Range | null;

package/dist/core/engine/dom.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Framework-free DOM helpers shared by every part of the editing engine: node type guards, lookups that never leave
+ * the editor root, element factories and the small structural fixes (caret placeholders, mark merging) that keep the
+ * editable markup predictable.
+ */
+/** Selector for blocks without editable text inside: rules, images and page breaks. */
+export declare const ATOM_SELECTOR = "hr, img, div[data-type=\"page-break\"]";
+/** Selector for blocks that hold editable inline text. */
+export declare const TEXT_BLOCK_SELECTOR = "p, h1, h2, h3, h4, h5, h6, pre";
+/** Marks the extra `<br>` that keeps an empty or break-terminated line visible; it is never serialised. */
+export declare const TRAILING_BREAK = "data-doc-trailing";
+/** Whether the node is an element. */
+export declare const isElement: (node: Node | null | undefined) => node is HTMLElement;
+/** Whether the node is a text node. */
+export declare const isText: (node: Node | null | undefined) => node is Text;
+/** Whether the node is a paragraph, heading or code block. */
+export declare const isTextBlock: (node: Node | null | undefined) => node is HTMLElement;
+/** Whether the node is an ordered or unordered list. */
+export declare const isList: (node: Node | null | undefined) => node is HTMLElement;
+/** Whether the node is a block without editable text (rule, image, page break). */
+export declare const isAtom: (node: Node | null | undefined) => node is HTMLElement;
+/** Whether the node is a `<br>`, placeholder or real. */
+export declare const isBreak: (node: Node | null | undefined) => node is HTMLBRElement;
+/** Whether the node is the editor's placeholder `<br>` rather than a line break typed by the user. */
+export declare const isTrailingBreak: (node: Node | null | undefined) => boolean;
+/** Nearest ancestor-or-self matching the predicate, never leaving `root` (which itself is never returned). */
+export declare const closestWithin: (node: Node | null | undefined, root: HTMLElement, predicate: (element: HTMLElement) => boolean) => HTMLElement | null;
+/** Nearest ancestor-or-self inside `root` whose tag is `tags` or one of `tags`. */
+export declare const closestTag: (node: Node | null | undefined, root: HTMLElement, tags: string | ReadonlySet<string>) => HTMLElement | null;
+/** The paragraph, heading or code block containing `node`. */
+export declare const closestTextBlock: (node: Node | null | undefined, root: HTMLElement) => HTMLElement | null;
+/** Creates an element with attributes and children in one call. */
+export declare const createElement: <K extends keyof HTMLElementTagNameMap>(tag: K, attributes?: Record<string, string>, children?: Array<Node | string>) => HTMLElementTagNameMap[K];
+/** Creates the placeholder `<br>` that gives empty lines their height. */
+export declare const createTrailingBreak: () => HTMLBRElement;
+/** Creates a paragraph with the given inline content and the placeholder break it needs. */
+export declare const createParagraph: (children?: Node[]) => HTMLParagraphElement;
+/** Whether the element contains text, an image or a real line break. */
+export declare const hasVisibleContent: (element: Element) => boolean;
+/** Whether a text block has no text and no image, holding at most one break. */
+export declare const isEmptyTextBlock: (block: Element) => boolean;
+/**
+ * Keeps exactly one placeholder `<br>` where the browser needs it: in empty blocks and after a user line break at the
+ * end of a block. Leaves the DOM untouched when nothing has to change, so the caret is not disturbed while typing.
+ */
+export declare const syncTrailingBreak: (block: HTMLElement) => void;
+/** Replaces an element with its own children. */
+export declare const unwrap: (element: Element) => void;
+/** Replaces the element with one of another tag, keeping attributes and children. */
+export declare const renameElement: <T extends HTMLElement = HTMLElement>(element: HTMLElement, tag: string) => T;
+/** Removes marks that no longer contain anything the user can see or place a caret into. */
+export declare const removeEmptyMarks: (scope: HTMLElement) => void;
+/** Joins neighbouring marks with identical tag and attributes, then merges adjacent text nodes. */
+export declare const mergeAdjacentMarks: (scope: HTMLElement) => void;
+/** All paragraphs, headings and code blocks inside `scope`, in document order. */
+export declare const textBlocksWithin: (scope: ParentNode) => HTMLElement[];
+/** Text blocks touched by the range, in document order. */
+export declare const textBlocksInRange: (root: HTMLElement, range: Range) => HTMLElement[];
+/** Whether nothing visible precedes the point inside its block. */
+export declare const isAtBlockStart: (block: HTMLElement, container: Node, offset: number) => boolean;
+/** Whether nothing visible follows the point inside its block. */
+export declare const isAtBlockEnd: (block: HTMLElement, container: Node, offset: number) => boolean;
+/** Escapes regular-expression syntax so user text can be searched literally. */
+export declare const escapeRegExp: (value: string) => string;

package/dist/core/engine/editing.d.ts

@@ -0,0 +1,44 @@
+/** A collapsed DOM position returned by edits so the engine can restore the caret. */
+export interface Caret {
+    /** Container node of the position. */
+    node: Node;
+    /** Offset inside `node`: a character index for text, a child index for elements. */
+    offset: number;
+}
+/** Caret before the first character of a block (or inside it when it has no text). */
+export declare const startCaret: (block: HTMLElement) => Caret;
+/** Caret after the last character of a block, before its caret placeholder when it has no text. */
+export declare const endCaret: (block: HTMLElement) => Caret;
+/** Deletes the selected content. The caret should be restored to the range start by the caller. */
+export declare const deleteRange: (root: HTMLElement, range: Range) => void;
+/**
+ * Backspace at the very start of a text block: lifts it out of a list or quote, deletes a preceding atom,
+ * moves into a preceding table, or merges it into the previous text block of the same cell.
+ * @returns the new caret, or `null` when nothing applies.
+ */
+export declare const joinBackward: (root: HTMLElement, block: HTMLElement) => Caret | null;
+/**
+ * Delete at the very end of a text block: deletes a following atom or merges the next text block of the same
+ * cell into this one.
+ * @returns the new caret, or `null` when nothing applies.
+ */
+export declare const joinForward: (root: HTMLElement, block: HTMLElement) => Caret | null;
+/**
+ * Enter at a collapsed range: a newline in code blocks, leaving an empty list item or quote, or splitting the
+ * block (and its list item). A new line after a heading becomes a paragraph.
+ */
+export declare const splitAtCaret: (root: HTMLElement, range: Range) => Caret | null;
+/** Shift+Enter: a `<br>` line break, or a newline inside code blocks. */
+export declare const insertLineBreak: (root: HTMLElement, range: Range) => Caret | null;
+/** Inserts plain text at a collapsed range, creating a paragraph if the caret sits between blocks. */
+export declare const insertTextAtCaret: (root: HTMLElement, range: Range, text: string) => Caret;
+/**
+ * Pastes sanitised blocks at a collapsed range. A single paragraph flows into the current line; several blocks
+ * split the current block, with the first and last pasted paragraphs merging into its halves as in Word.
+ * @returns the caret after the inserted content.
+ */
+export declare const insertFragment: (root: HTMLElement, range: Range, fragment: DocumentFragment) => Caret | null;
+/** Whether the range is collapsed before any visible content of the block. */
+export declare const isCaretAtBlockStart: (block: HTMLElement, range: Range) => boolean;
+/** Whether the range is collapsed after all visible content of the block. */
+export declare const isCaretAtBlockEnd: (block: HTMLElement, range: Range) => boolean;