nuvra 0.5.0 → 0.6.0

package/README.md

@@ -1,15 +1,16 @@
 # 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, comments, HTML source mode, printing, export to HTML and Word files
-(`.docx`) you can open again.
+forms, tables, images, lists, find & replace, comments, HTML source mode, printing, PDF download, export to HTML and Word
+files (`.docx`) you can open again.
 
 **[Documentation and live demo →](https://nuvra-docs.vercel.app)**
 
 - No editor framework underneath: its own small editing engine with a sanitizing schema.
 - No UI framework either: native HTML controls, built-in SVG icons and plain CSS variables. Vue is the only
   dependency.
-- Pagination in the page view (A4, A5, Letter, …, portrait or landscape).
+- Pagination in the page view (A4, A5, Letter, …, portrait or landscape), with section breaks for landscape pages inside a
+  portrait document.
 - 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.
 - Office tools: format painter, letter case, paragraph spacing, formatting marks, a right-click menu and
@@ -18,10 +19,12 @@ forms, tables, images, lists, find & replace, comments, HTML source mode, printi
   the editor shows them, and the Word export uses Word's own header, footer and page fields.
 - A ruler above the page for the margins and for the first line, left and right indents of a paragraph.
 - A page watermark such as DRAFT or COPY, drawn behind the text of every page and carried into print, HTML and Word.
-- Real `.docx` export and import, multilevel (1.1.1) numbering, a table of contents and a navigation pane.
+- Real `.docx` export and import, PDF download without the print dialog, multilevel (1.1.1) numbering, a table of
+  contents and a navigation pane with headings and page thumbnails.
 - Footnotes at the bottom of their page, carried into print and Word.
 - Comments with replies, tracked changes that round-trip with Word, a comparison of two versions, and templates
   filled in as a form.
+- Hooks for editing together: other people's carets and selections, your selection as character positions.
 - A `/` command menu and a toolbar slot for your own commands and buttons.
 
 ## Installation
@@ -103,6 +106,7 @@ const uploadImage: DocumentImageUploadHandler = async file => {
 | `author`          | `string`                          | `''`     | Name written on new comments, replies and tracked changes.                 |
 | `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.                                   |
+| `collaborators`   | `Collaborator[]`                  | `[]`     | Other people editing the document; their carets and selections are drawn.  |
 | `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`. |
@@ -119,18 +123,20 @@ const uploadImage: DocumentImageUploadHandler = async file => {
 | `variables`       | `TemplateVariable[]`              | `[]`     | Template variables the user can insert.                                    |
 
 `Editor` accepts the same props except `v-model:page`, `v-model:comments`, `v-model:trackChanges`, `author`,
-`defaultViewMode`, `height`, `ruler`, `slashCommands` and `title`.
+`collaborators`, `defaultViewMode`, `height`, `ruler`, `slashCommands` 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.       |
-| `importError` | `error: unknown` | A Word file could not be read.                    |
+| 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.                    |
+| `importError`     | `error: unknown`                    | A Word file could not be read.                                 |
+| `exportError`     | `error: unknown`                    | The PDF could not be drawn; no file is downloaded.             |
+| `selectionChange` | `selection: SelectionOffsets \| null` | The caret or selection moved; `null` when it left the document. |
 
 ### Exposed methods (`DocumentEditor` ref)
 
@@ -144,6 +150,7 @@ Numbers are pixels; strings are used as CSS lengths (`'100%'`, `'50vh'`).
 | `print()`                 | Opens the browser print dialog.                                  |
 | `exportHtml()`            | Downloads the document as an HTML page.                          |
 | `exportWord()`            | Downloads the document as a Word file (`.docx`).                 |
+| `exportPdf()`             | Downloads the document as a PDF drawn from its pages.            |
 | `engine`                  | The editing engine (`DocumentEngine`), for advanced integrations. |
 
 ### Keyboard shortcuts
@@ -210,8 +217,25 @@ const submit = () => {
 footers with page fields, the watermark, lists, tables with merged cells, images, footnotes and tracked changes as
 Word revisions. "Open Word file (.docx)" (or `importWord(file)`) loads one into the editor, footnotes and revisions
 included; a file that cannot be read emits `importError`. `buildDocx` and `readDocx` do the same in your own code. A
-document with several sections gets the page setup of its last section, and the content of a different first page
-header is not imported.
+document with several sections takes the page setup of its first section, and every further section starts with a
+section break; the content of a different first page header is not imported.
+
+### PDF download
+
+"Download as PDF" in the "More" menu, or `exportPdf()`, saves a PDF without the print dialog. Every sheet is drawn into a
+picture (SVG `foreignObject` → canvas → JPEG) and written into the PDF, so it looks like the printout, but its text
+cannot be selected or searched. Images from servers without CORS are left out, and in the web view the editor switches to
+the page view for the moment of the export. A PDF that cannot be drawn emits `exportError`; printing with "Save as PDF"
+still gives a PDF with real text.
+
+### Pages in different orientations
+
+"Section break: landscape pages" and "Section break: portrait pages" in the insert menu and the `/` menu (or
+`engine.insertSectionBreak('landscape')`) turn the pages after the break; paper size and margins stay, and the break
+starts a new page. It is saved as `<div data-type="section-break" data-orientation="landscape"></div>`. The page view
+draws sheets of different sizes and gives the blocks of a turned section their sheet's text width; printing uses a named
+`@page` for turned sheets, the PDF has turned pages, and the Word export writes every section as a Word section with its
+own orientation.
 
 ### Footnotes
 
@@ -225,7 +249,8 @@ From code: `engine.insertFootnote(text)`, `setFootnoteText(element, text)`, `rem
 For long documents the toolbar offers multilevel numbering (1., 1.1., 1.1.1., saved as `<ol data-numbering="legal">`),
 a table of contents of the headings with page numbers (saved as `<table data-type="toc">`, refreshed with
 `updateTableOfContents()`), and a navigation pane. `PageSettings` has `differentFirstPage` to hide the header, footer
-and page number on the first page, and `firstPageNumber` for the number printed on it.
+and page number on the first page, and `firstPageNumber` for the number printed on it. The navigation pane lists the
+headings or shows page thumbnails; clicking one scrolls to it.
 
 ## Comments, tracked changes and comparison
 
@@ -253,12 +278,13 @@ const save = () =>
 </template>
 ```
 
-Users select text and press "Add comment" (`Ctrl/⌘+Alt+M`); the "Comments" panel replies, resolves, reopens and
-deletes them, and flags comments whose text was deleted.
+The comment and change tools are in the **Review** menu of the toolbar. Users select text and choose "Add comment"
+(`Ctrl/⌘+Alt+M`); the "Comments" panel replies, resolves, reopens and deletes them, and flags comments whose text was
+deleted.
 
 ### Tracked changes
 
-Bind `v-model:trackChanges` (or press "Track changes") to record typing, deleting, cut and paste as tracked changes
+Bind `v-model:trackChanges` (or choose "Track changes" in the Review menu) to record typing, deleting, cut and paste as tracked changes
 by `author`. They are part of the HTML, `<ins data-change="id" data-author="…" data-time="…">` and `<del …>`, shown
 and printed green-underlined and red-struck. The "Changes" panel accepts or rejects them one by one or all at once;
 from code use `engine.getChanges()`, `engine.resolveChanges(accept, id?)` and `engine.selectChange(id)`. Formatting,
@@ -277,9 +303,39 @@ shown whole. `compareDocuments(before, after)` returns the same HTML and counts
 <DocumentCompare :before="previousVersion" :after="html" :height="600" />
 ```
 
+## Editing together
+
+The editor has hooks for several people on one document; the transport (WebSocket, WebRTC, …) is up to your app.
+`selectionChange` reports your caret or selection as character positions, `collaborators` draws other people's carets
+(with names) and selections, and a new `v-model` value from outside keeps your caret at the same character position.
+The engine also offers `getSelectionOffsets()`, `getOffsetRects(offsets)` and `setContent(html, { keepSelection })`;
+`collaboratorColor` gives the colour a collaborator is drawn in.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { type Collaborator, DocumentEditor, type SelectionOffsets } from 'nuvra';
+
+const html = ref('');
+const collaborators = ref<Collaborator[]>([]); // filled from your socket messages
+
+const sendSelection = (selection: SelectionOffsets | null) =>
+  socket.send(JSON.stringify({ type: 'selection', id: me.id, name: me.name, selection }));
+</script>
+
+<template>
+  <DocumentEditor v-model="html" :collaborators="collaborators" @selection-change="sendSelection" />
+</template>
+```
+
+This is not a CRDT: the document travels as a whole, so when two people type at the same time the document sent last
+wins, and because positions are character offsets, a remote edit before your caret shifts it. A library such as Yjs
+can carry the document and the selections (awareness), but edits are still not merged character by character. See the
+[guide](https://nuvra-docs.vercel.app/docs/collaboration).
+
 ## Commands and toolbar buttons
 
-Typing `/` at the start of a line or after a space opens a command menu: headings, lists, table, page break, footnote,
+Typing `/` at the start of a line or after a space opens a command menu: headings, lists, table, page and section breaks, footnote,
 table of contents, dates, signature blocks and your variables. `slashCommands` adds your own commands at the top, and the
 `toolbar` slot adds your own buttons:
 

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

@@ -1,3 +1,4 @@
+import type { Collaborator, SelectionOffsets } from '../core/collaboration';
 import { type DocumentComment } from '../core/comments';
 import { DocumentEngine } from '../core/engine/engine';
 import { type EditorLocaleInput } from '../core/labels';
@@ -15,6 +16,8 @@ interface Props {
     autofocus?: boolean;
     /** Gray space around the page or web sheet that separates the document from the editor frame. */
     canvasPadding?: CssSize;
+    /** Other people editing the document; their carets and selections are drawn over it. */
+    collaborators?: readonly Collaborator[];
     /** Name written as the author of new comments, replies and tracked changes. */
     author?: string;
     /** View shown first; form fields use the lighter web view. */
@@ -76,6 +79,8 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_PublicProps, {
     exportHtml: () => Promise<void>;
     /** Downloads the document as a Word-compatible file. */
     exportWord: () => Promise<void>;
+    /** Downloads the document as a PDF drawn from its pages. */
+    exportPdf: () => Promise<void>;
     /** Moves keyboard focus into the document. */
     focus: () => void | undefined;
     /** Returns the document HTML, including edits not yet written to the model. */
@@ -94,6 +99,8 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_PublicProps, {
     "update:page": (value: PageSettings) => any;
     uploadError: (error: unknown) => any;
     importError: (error: unknown) => any;
+    exportError: (error: unknown) => any;
+    selectionChange: (selection: SelectionOffsets | null) => any;
     "update:modelValue": (value: string) => any;
     "update:trackChanges": (value: boolean) => any;
     "update:comments": (value: DocumentComment[] | undefined) => any;
@@ -103,6 +110,8 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_PublicProps, {
     "onUpdate:page"?: ((value: PageSettings) => any) | undefined;
     onUploadError?: ((error: unknown) => any) | undefined;
     onImportError?: ((error: unknown) => any) | undefined;
+    onExportError?: ((error: unknown) => any) | undefined;
+    onSelectionChange?: ((selection: SelectionOffsets | null) => any) | undefined;
     "onUpdate:modelValue"?: ((value: string) => any) | undefined;
     "onUpdate:trackChanges"?: ((value: boolean) => any) | undefined;
     "onUpdate:comments"?: ((value: DocumentComment[] | undefined) => any) | undefined;
@@ -114,6 +123,7 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_PublicProps, {
     placeholder: string;
     disabled: boolean;
     minHeight: CssSize;
+    collaborators: readonly Collaborator[];
     maxHeight: CssSize;
     maxLength: number;
     variables: readonly TemplateVariable[];

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

@@ -2,6 +2,7 @@ import type { ParagraphIndents } from '../core/engine/blocks';
 import type { DocumentEngine } from '../core/engine/engine';
 import { type SheetFootnote } from '../core/footnotes';
 import { type DocumentViewMode, type PageMargins, type PageMetrics, type PageSettings } from '../core/page';
+import { type SheetGeometry } from '../core/pagination';
 interface Props {
     /** Grow with the content between the editor's min and max height instead of filling a fixed height. */
     autoHeight: boolean;
@@ -21,6 +22,8 @@ interface Props {
     metrics: PageMetrics;
     /** Number of sheets drawn behind the content in page view. */
     pageCount: number;
+    /** Position, size and orientation of every sheet, as laid out by pagination; empty until the first layout. */
+    sheets: readonly SheetGeometry[];
     /** Whether the ruler is drawn above the sheet; it is only ever shown in the page view. */
     rulerVisible: boolean;
     /** Paginated sheets or a single web sheet. */

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

@@ -0,0 +1,17 @@
+import { type Collaborator } from '../core/collaboration';
+import type { DocumentEngine } from '../core/engine/engine';
+interface Props {
+    /** Engine that measures positions in the document. */
+    engine: DocumentEngine;
+    /** People whose carets are drawn. */
+    collaborators: readonly Collaborator[];
+    /** Element the marks are positioned in; it must be positioned itself. */
+    container: HTMLElement;
+    /** Scrolling canvas; marks outside it are hidden. */
+    scrollTarget: HTMLElement;
+    /** Changes whenever the layout may move text (zoom, view mode, page setup), so the marks are measured again. */
+    layoutKey: string;
+}
+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-outline.vue.d.ts

@@ -1,16 +1,36 @@
-import type { OutlineHeading } from '../core/outline';
+import type { OutlineHeading, OutlineView } from '../core/outline';
+import type { PageMetrics } from '../core/page';
+import type { SheetGeometry } from '../core/pagination';
 interface Props {
     /** Headings of the document with the page each starts on, `null` outside the page view. */
     headings: ReadonlyArray<OutlineHeading & {
         page: number | null;
     }>;
+    /** Clean HTML of every sheet, shown as page thumbnails; empty outside the page view. */
+    pages: readonly string[];
+    /** Page geometry the thumbnails are scaled from. */
+    metrics: PageMetrics;
+    /** Size of every sheet; a sheet turned by a section break gets a turned thumbnail. */
+    sheets: readonly SheetGeometry[];
+    /** Number printed on the first sheet. */
+    firstPageNumber: number;
 }
-declare const __VLS_export: import("vue").DefineComponent<Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+type __VLS_Props = Props;
+type __VLS_ModelProps = {
+    /** Which list is shown; the editor reads it to lay out thumbnails only while they are visible. */
+    'view'?: OutlineView;
+};
+type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
+declare const __VLS_export: import("vue").DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     select: (heading: HTMLElement) => any;
     close: () => any;
-}, string, import("vue").PublicProps, Readonly<Props> & Readonly<{
+    selectPage: (index: number) => any;
+    "update:view": (value: OutlineView) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
     onSelect?: ((heading: HTMLElement) => any) | undefined;
     onClose?: (() => any) | undefined;
+    onSelectPage?: ((index: number) => any) | undefined;
+    "onUpdate:view"?: ((value: OutlineView) => any) | undefined;
 }>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;
 export default _default;

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

@@ -37,9 +37,9 @@ interface Props {
     /** Template variables offered by the variable menu; the menu is hidden without any. */
     variables: ReadonlyArray<TemplateVariable>;
 }
-declare var __VLS_604: {};
+declare var __VLS_626: {};
 type __VLS_Slots = {} & {
-    default?: (props: typeof __VLS_604) => any;
+    default?: (props: typeof __VLS_626) => any;
 };
 declare const __VLS_base: import("vue").DefineComponent<Props, {
     /** Opens the link popover. */

package/dist/core/collaboration.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Hooks for editing a document together. The editor reports where the caret is and draws the carets and selections
+ * of other people; sending the document and the selections between them (WebSocket, WebRTC, a CRDT such as Yjs) is
+ * left to the application.
+ */
+/** A selection as character positions through the document; equal positions are a caret. */
+export interface SelectionOffsets {
+    /** Where selecting started. */
+    anchor: number;
+    /** Where the caret is. */
+    focus: number;
+}
+/** Someone else editing the same document. */
+export interface Collaborator {
+    /** Stable id of the person or connection. */
+    id: string;
+    /** Name shown next to the caret. */
+    name: string;
+    /** CSS colour of the caret and the selection; one is picked from the id when it is left out. */
+    color?: string;
+    /** Where the person's caret or selection is, or `null` while they are not in the document. */
+    selection: SelectionOffsets | null;
+}
+/** The colour of a collaborator: their own, or a stable one derived from the id. */
+export declare const collaboratorColor: (collaborator: Pick<Collaborator, "id" | "color">) => string;

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

@@ -13,8 +13,15 @@ export declare const FOOTNOTE_ATTRIBUTE = "data-footnote";
 export declare const FOOTNOTE_SELECTOR = "sup[data-footnote]";
 /** Selector for every inline atom: elements inside a line that behave as one character and hold no editable text. */
 export declare const INLINE_ATOM_SELECTOR = "span[data-variable], sup[data-footnote]";
-/** 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 without editable text inside: rules, images, page breaks and section breaks. */
+export declare const ATOM_SELECTOR = "hr, img, div[data-type=\"page-break\"], div[data-type=\"section-break\"]";
+/** Whether a `<div>` is one of the break blocks the document model keeps: a page break or a section break. */
+export declare const isBreakBlock: (node: Node | null | undefined) => boolean;
+/**
+ * Creates a section break: the sheets after it are turned to `orientation`. It also starts a new sheet, so it is drawn
+ * and printed like a page break.
+ */
+export declare const createSectionBreak: (orientation: "portrait" | "landscape") => HTMLDivElement;
 /** 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. */

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

@@ -6,6 +6,7 @@ import { EditorHistory } from './history';
 import { type ListKind } from './lists';
 import { type MarkName, type StyleName, type TextCase } from './marks';
 import { SearchController, type SearchState } from './search';
+import { type TextBookmark } from './selection';
 import { type TableCell } from './tables';
 /** A tracked insertion or deletion; the parts of one edit are joined. */
 export interface TrackedChange {
@@ -162,10 +163,23 @@ export declare class DocumentEngine {
      * @param options.addToHistory Record the replacement as an undo step instead of clearing the history.
      * @param options.emitUpdate Emit `update` so the host saves the new content.
      */
-    setContent(html: string, { addToHistory, emitUpdate }?: {
+    setContent(html: string, { addToHistory, emitUpdate, keepSelection }?: {
         addToHistory?: boolean | undefined;
         emitUpdate?: boolean | undefined;
+        keepSelection?: boolean | undefined;
     }): void;
+    /**
+     * The selection as character positions through the document: `anchor` where selecting started, `focus` where the
+     * caret is. Positions survive changes to the markup, so they can be sent to other people editing the document.
+     */
+    getSelectionOffsets(): TextBookmark | null;
+    /**
+     * Viewport rectangles of the text between two character positions, for drawing someone else's selection; a
+     * collapsed position gives the rectangle of its caret line with no width.
+     */
+    getOffsetRects(offsets: TextBookmark): DOMRect[];
+    /** Number of character positions in the document, the largest offset a selection can have. */
+    private characterPositions;
     /** Switches between editing and read-only mode. */
     setEditable(editable: boolean): void;
     /** Word and character counts of the document text. */
@@ -395,6 +409,8 @@ export declare class DocumentEngine {
     private insertBlock;
     /** Inserts a horizontal rule. */
     insertHorizontalRule(): void;
+    /** Inserts a section break: the sheets after it are turned to `orientation`, for example for a wide table. */
+    insertSectionBreak(orientation: 'portrait' | 'landscape'): void;
     /** Inserts a manual page break. */
     insertPageBreak(): void;
     /**

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

@@ -2,6 +2,8 @@
 export declare const VARIABLE_NAME: RegExp;
 /** Attribute holding the label a variable chip shows in the editor; editor-only. */
 export declare const VARIABLE_LABEL_ATTRIBUTE = "data-label";
+/** Attribute pagination writes on blocks of a section turned against the document's orientation; editor-only. */
+export declare const ROTATED_ATTRIBUTE = "data-doc-rotated";
 /** Attribute pagination writes on blocks it moved to the next sheet; editor-only. */
 export declare const GAP_ATTRIBUTE = "data-doc-gap";
 /** Class marking table cells in a drag selection; editor-only. */

package/dist/core/export.d.ts

@@ -9,6 +9,8 @@ interface DocumentSnapshot {
      * with real page numbers and breaks the pages exactly where the editor shows them.
      */
     pages?: string[];
+    /** For every sheet of `pages`, whether a section break turned it against the document's orientation. */
+    rotated?: boolean[];
     /** Footnotes of every sheet of `pages`; without pages, the notes of all of them are printed after the document. */
     footnotes?: SheetFootnote[][];
     /** Document title, used for the print title and file names. */
@@ -16,6 +18,11 @@ interface DocumentSnapshot {
     /** Page size, orientation, margins and the running texts. */
     page: PageSettings;
 }
+/** Paper width and height in millimetres, in the chosen orientation. */
+export declare const paperSize: ({ size, orientation }: PageSettings) => {
+    width: number;
+    height: number;
+};
 /** Turns a document title into a safe file name without extension. */
 export declare const toFileName: (title: string) => string;
 /**
@@ -24,7 +31,7 @@ export declare const toFileName: (title: string) => string;
  * the pages break where the editor shows them; without them the document flows and the browser repeats one fixed
  * header and footer on every page.
  */
-export declare const buildPrintableHtml: ({ html, pages, footnotes, title, page }: DocumentSnapshot) => string;
+export declare const buildPrintableHtml: ({ html, pages, rotated, footnotes, title, page }: DocumentSnapshot) => string;
 /** Offers text or binary content as a file download. */
 export declare const downloadFile: (content: string | Blob, fileName: string, type: string) => void;
 /** Prints through a detached iframe so the application chrome never ends up on paper. Waits for images first. */

package/dist/core/locales/uz.d.ts

@@ -59,6 +59,7 @@ export declare const uz: {
     readonly 'editor.enterFullscreen': "To‘liq ekran";
     readonly 'editor.exitFullscreen': "To‘liq ekrandan chiqish";
     readonly 'editor.exportHtml': "HTML sifatida yuklab olish";
+    readonly 'editor.exportPdf': "PDF sifatida yuklab olish";
     readonly 'editor.exportWord': "Word (.docx) sifatida yuklab olish";
     readonly 'editor.fitWidth': "Kenglikka moslash";
     readonly 'editor.fontFamily': "Shrift";
@@ -112,6 +113,10 @@ export declare const uz: {
     readonly 'editor.numbering.legal': "Ko‘p darajali raqamlash (1.1, 1.2)";
     readonly 'editor.outline': "Navigatsiya paneli";
     readonly 'editor.outline.empty': "Hujjatda sarlavhalar yo‘q. Sarlavha uslubini qo‘llang, ular shu yerda ko‘rinadi.";
+    readonly 'editor.outline.headings': "Sarlavhalar";
+    readonly 'editor.outline.noPages': "Sahifalar faqat sahifa ko‘rinishida chiqadi.";
+    readonly 'editor.outline.page': "{page}-sahifa";
+    readonly 'editor.outline.pages': "Sahifalar";
     readonly 'editor.openLink': "Havolani ochish";
     readonly 'editor.or': "yoki havola orqali";
     readonly 'editor.orderedList': "Raqamli ro‘yxat";
@@ -147,6 +152,7 @@ export declare const uz: {
     readonly 'editor.replace.one': "Almashtirish";
     readonly 'editor.replace.placeholder': "Almashtirish";
     readonly 'editor.replace.toggle': "Almashtirishni ko‘rsatish";
+    readonly 'editor.review': "Taqriz: izohlar va o‘zgarishlar";
     readonly 'editor.ruler': "Chizg‘ich";
     readonly 'editor.ruler.firstLine': "Birinchi qator chekinishi";
     readonly 'editor.ruler.indentLeft': "Chap chekinish";
@@ -160,6 +166,8 @@ export declare const uz: {
     readonly 'editor.search.title': "Qidirish va almashtirish";
     readonly 'editor.search.wholeWord': "Butun so‘z";
     readonly 'editor.selectAll': "Barchasini tanlash";
+    readonly 'editor.sectionBreak.landscape': "Bo‘lim uzilishi: albom sahifalar";
+    readonly 'editor.sectionBreak.portrait': "Bo‘lim uzilishi: kitob sahifalar";
     readonly 'editor.signature': "Imzo bloki";
     readonly 'editor.signature.agreed': "KELISHILDI grifi";
     readonly 'editor.signature.approval': "TASDIQLAYMAN grifi";

package/dist/core/outline.d.ts

@@ -12,6 +12,8 @@ export interface OutlineHeading {
     /** The heading element in the editable document. */
     element: HTMLElement;
 }
+/** What the navigation panel lists: the headings, or thumbnails of the pages. */
+export type OutlineView = 'headings' | 'pages';
 /** A line of the table of contents. */
 export interface TableOfContentsEntry {
     /** Heading level, 1 to 6; deeper levels are indented. */

package/dist/core/pagination.d.ts

@@ -1,5 +1,18 @@
 import { type SheetFootnote } from './footnotes';
-import type { PageMetrics } from './page';
+import type { PageMetrics, PageOrientation } from './page';
+/** Where a sheet is drawn and which way it is turned. */
+export interface SheetGeometry {
+    /** Distance of the sheet from the top of the first sheet, in pixels. */
+    top: number;
+    /** Sheet width in pixels. */
+    width: number;
+    /** Sheet height in pixels. */
+    height: number;
+    /** Orientation of the sheet. */
+    orientation: PageOrientation;
+    /** Whether the sheet is turned against the document's own orientation, by a section break. */
+    rotated: boolean;
+}
 /** Handle returned by {@link createPagination}. */
 export interface PaginationController {
     /** Sets the page geometry and re-runs the layout; pass `null` to switch pagination off (web view). */
@@ -15,15 +28,21 @@ interface PaginationOptions {
     onPageCount: (count: number) => void;
     /** Receives the footnotes of every sheet whenever they change; the web view is one sheet holding all of them. */
     onFootnotes?: (sheets: SheetFootnote[][]) => void;
+    /** Receives the position, size and orientation of every sheet whenever they change; empty in the web view. */
+    onSheets?: (sheets: SheetGeometry[]) => void;
     /** Whether an IME composition is in progress, during which blocks must not move. */
     isComposing: () => boolean;
 }
+/** Sheets of a document without section breaks, all alike. */
+export declare const uniformSheets: (metrics: PageMetrics, count: number) => SheetGeometry[];
+/** Index of the sheet a vertical position falls on, counted from the top of the first sheet. */
+export declare const sheetIndexAt: (sheets: readonly SheetGeometry[], offset: number) => number;
 /**
  * Splits the laid-out document into the clean HTML of every sheet, for printing and export. Pagination has already
  * moved every block onto its page, so a block belongs to the page its top falls on; blocks taller than a page stay
  * whole, exactly as they are shown on screen. Footnote references keep their document-wide numbers.
  */
-export declare const splitIntoPages: (root: HTMLElement, metrics: PageMetrics, pageCount: number) => string[];
+export declare const splitIntoPages: (root: HTMLElement, metrics: PageMetrics, pageCount: number, geometry?: readonly SheetGeometry[]) => string[];
 /**
  * Keeps the document laid out on sheets. Layout passes are batched to one per animation frame and re-run when the
  * document resizes, images or fonts load, or the host schedules one after an edit.

package/dist/core/pdf.d.ts

@@ -0,0 +1,43 @@
+/**
+ * PDF download without the print dialog and without dependencies. Every sheet of the printable document is drawn into
+ * a canvas through an SVG `foreignObject`, and the pictures are written into a PDF, one per page. The PDF looks like
+ * the printout, but its text cannot be selected or searched.
+ */
+/** A rendered page: a JPEG picture of the sheet and the paper size it is printed on. */
+export interface PdfPage {
+    /** JPEG data of the page picture. */
+    jpeg: Uint8Array;
+    /** Picture width in pixels. */
+    width: number;
+    /** Picture height in pixels. */
+    height: number;
+    /** Paper width in PDF points (1/72 inch). */
+    widthPt: number;
+    /** Paper height in PDF points. */
+    heightPt: number;
+}
+/** Options of {@link renderPdf}. */
+export interface PdfOptions {
+    /** Pixels per CSS pixel of the page pictures; higher is sharper and larger. Defaults to 2. */
+    scale?: number;
+    /** JPEG quality between 0 and 1. Defaults to 0.92. */
+    quality?: number;
+}
+/** MIME type of PDF files. */
+export declare const PDF_MIME = "application/pdf";
+/**
+ * Writes JPEG pictures into a PDF document, one picture filling each page.
+ *
+ * @returns the PDF file content.
+ */
+export declare const buildPdf: (pages: readonly PdfPage[]) => Uint8Array;
+/**
+ * Turns the printable HTML of a paginated document (one `section.doc-sheet` per page) into a PDF.
+ *
+ * @param printableHtml Standalone HTML as built for printing from the page view.
+ * @param paper Paper width and height in millimetres, in the chosen orientation.
+ */
+export declare const renderPdf: (printableHtml: string, paper: {
+    width: number;
+    height: number;
+}, options?: PdfOptions) => Promise<Blob>;

package/dist/core/types.d.ts

@@ -1,3 +1,3 @@
 /** Uploads an image and resolves with its public URL. Without a handler, images are embedded as data URLs. */
 export type DocumentImageUploadHandler = (file: File) => Promise<string>;
-export type DocumentMenuAction = 'source' | 'print' | 'exportHtml' | 'exportWord' | 'importWord' | 'formattingMarks' | 'ruler' | 'outline' | 'tableOfContents' | 'comments' | 'addComment' | 'footnote' | 'trackChanges' | 'changes' | 'fullscreen';
+export type DocumentMenuAction = 'source' | 'print' | 'exportHtml' | 'exportWord' | 'exportPdf' | 'importWord' | 'formattingMarks' | 'ruler' | 'outline' | 'tableOfContents' | 'comments' | 'addComment' | 'footnote' | 'trackChanges' | 'changes' | 'fullscreen';