@betteroffice/docx 0.2.0 → 0.3.0

package/README.md

@@ -53,9 +53,9 @@ provider.connect();
 
 `replica` can be a direct `YrsSession`, the worker-aware adapter returned by
 `createWorkerCollaborationReplica`, or the value published by the React
-editor's `collaboration.onReplica` callback. The provider speaks Yjs sync-v1;
-room routing, authentication, awareness, and reconnection policy remain
-transport concerns. Pass a persisted Yrs update as `collaboration.initialUpdate`
+editor's `collaboration.onReplica` callback. The provider handles Yjs sync-v1 and
+awareness; room routing, authentication, and reconnection remain transport
+concerns. Pass a persisted Yrs update as `collaboration.initialUpdate`
 when a React editor joins an existing room so it hydrates the shared history
 instead of independently importing the same DOCX.
 
@@ -68,3 +68,522 @@ Package builds, demo startup, and CI run this step automatically.
 
 [JavaScript guide](https://docs.betteroffice.dev/docs/javascript) ·
 [Changelog](https://github.com/openooxml/betteroffice/blob/main/packages/docx/CHANGELOG.md) · Apache-2.0.
+
+### Undo capture modes and boundaries
+
+`session.setUndoCaptureMode(mode)` selects how tracked local transactions are
+combined into undo steps. `session.undoCaptureMode()` returns the current mode.
+
+| Mode | Grouping |
+| --- | --- |
+| `auto` (default) | Edits within 500 ms coalesce; switching stories closes the group. |
+| `manual` | Edits coalesce across pauses and stories until an explicit boundary. |
+
+`session.addUndoBoundary()` closes the current group in any mode. Changing modes
+also closes the group; setting the same mode again does not. Both operations
+preserve undo/redo history and are safe before capture starts. Repeated boundaries
+create no empty undo steps. Remote transactions remain outside local undo history.
+
+```ts
+session.setUndoCaptureMode('manual');
+session.insertText(firstLocation, 'Prefixo ');
+session.insertText(secondLocation, 'Suffix');
+session.addUndoBoundary();
+session.deleteRange(markerRange);
+session.addUndoBoundary();
+session.setUndoCaptureMode('auto');
+```
+
+The two insertions undo together; marker deletion is a separate step. Boundaries
+are also available in automatic mode when a host action needs to be isolated from
+surrounding typing. Undo/redo close capture as usual. Manual mode groups history;
+edit batches provide atomic execution.
+The host must close manual groups so later unrelated edits do not join them.
+
+### Paragraph identities
+
+A session addresses paragraphs by session keys (`YrsLoc.paraId`); Word stores its
+own paragraph ID (`w14:paraId`) in the file. A session anchor resolves on every
+replica of one collaborative session, and each seeding open (`openDocx`, `seedFromDocx`, `documentToYrs`) starts a new one unless given a fixed
+`generation`, as a deterministic shared seed needs. Source IDs are kept as authored, and every
+paragraph authored in the session gets a fresh, valid ID that avoids every ID the
+package already uses.
+
+`saveYrsDocx(session)` saves a session opened from DOCX bytes and returns each saved
+paragraph's persisted anchor, qualified by its package part:
+
+```ts
+import { createYrsSession, saveYrsDocx } from '@betteroffice/docx/yrs';
+
+const { secondParaId } = session.splitParagraph({ story: 'body', paraId, offset: 12 });
+const saved = await saveYrsDocx(session);
+const anchor = saved.paragraphs.find((p) => p.session.paraId === secondParaId)!.persisted;
+
+const reopened = await createYrsSession();
+reopened.openDocx(saved.bytes, true);
+reopened.resolveParagraphAnchor(anchor); // { status: 'found', anchor: { kind: 'session', … } }
+```
+
+`saved.conflicts` lists saved paragraphs whose ID the live session reassigned while the
+save ran, such as by a duplicate repair after a remote update; their anchors find them in
+the saved bytes only. The React editor's Save writes and records these IDs. `saveYrsDocx`
+also returns anchors and preserves unchanged source parts. `session.persistParagraphIds()`
+assigns IDs to source paragraphs without one across every story part, comments,
+note separators and retained XML included, and repairs duplicates: source IDs and
+saved IDs keep theirs over copies. It refuses, changing nothing, rather than guess at
+an ambiguous comment reference. The change is replicated, stays out of undo history,
+and later saves keep it; a save whose stories are otherwise unchanged patches the IDs
+into the source bytes. `session.paragraphIdentities()` lists each paragraph's session,
+persisted and exact-source anchors. A persisted anchor is scoped to the document the
+host chose, and repeated source IDs resolve as `ambiguous`.
+
+### Selection state
+
+`session.selectionContext(range)` aggregates the range for toolbars and
+assistive technology. Toggle marks, including `superscript` and `subscript`,
+are `true`, `false` or `'mixed'`; value marks such as `fontFamily`, `color` and
+`highlight` are `null` when absent or not uniform. `highlight` reports Word's
+highlight name (`'yellow'`) or an unmapped hex value. `toggleMark` accepts
+`{ type: 'superscript' }` and `{ type: 'subscript' }`; adding one clears the other.
+
+### Version-checked edit batches
+
+Read what you will target together with the session version, then apply a batch
+against that version. Every step resolves against the state that was read; the
+batch commits as one transaction or returns a typed refusal with nothing changed.
+
+```ts
+const read = session.readParagraphs({ story: 'body', view: 'accepted' });
+if (!read.ok) throw new Error(read.failure.message);
+const clause = read.paragraphs.find((paragraph) => paragraph.text.startsWith('Term'))!;
+
+const result = session.applyEdits({
+  expectVersion: read.version,
+  steps: [
+    {
+      op: 'replaceText',
+      target: { kind: 'search', text: '30 days', view: 'accepted',
+        within: { kind: 'paragraph', story: 'body', paraId: clause.paraId } },
+      text: '45 days',
+      expect: { text: '30 days' },
+    },
+    {
+      op: 'insertParagraphs',
+      target: { story: 'body', paraId: clause.paraId },
+      at: 'end',
+      paragraphs: [{ text: 'Renewal is automatic.' }],
+    },
+  ],
+});
+if (!result.ok) console.warn(result.failure.code, result.failure.message);
+```
+
+`version()` changes with every committed change, local or remote (including
+undo and redo), and when the session reopens its document. Tokens are scoped to
+one session; after a lost response, read again rather than retrying with a new
+version.
+
+Offsets are UTF-16 positions into a paragraph's projected text. Each inline atom
+(hard break, image, content control, note reference, field, other embed) is one
+U+FFFC listed in `atoms`, tabs stay `\t`, and paragraph marks are excluded. The
+`accepted` view includes pending insertions and hides pending deletions;
+`original` does the reverse. `findText` is exact, case-sensitive and
+paragraph-local, and a `search` target must match exactly once in its scope.
+
+| Step | Effect |
+| --- | --- |
+| `insertText` | Inserts at the start or end of a target, formatted like typing there. |
+| `replaceText` | Replaces a target's text inside one paragraph, keeping the paragraph. |
+| `deleteText` | Deletes a target's text inside one paragraph. |
+| `insertParagraphs` | Inserts complete paragraphs before or after an anchor, in the given or the anchor's style. |
+| `deleteParagraphs` | Deletes a contiguous span of complete paragraphs without merging properties into a neighbour. |
+| `setParagraphStyle` | Applies a document paragraph style with its paragraph and run formatting. |
+
+Refusals carry a `code` (`stale-version`, `missing-target`, `ambiguous-target`,
+`content-mismatch`, `overlapping-steps`, `locked-target`,
+`tracked-revision-conflict`, `unsupported`, `invalid-step`, `limit-exceeded`),
+the failing `stepIndex`, and the target. Editor hosts add `read-only` for an
+editor that does not accept edits. Malformed requests throw.
+`validateEdits(request)` runs the same checks and previews each step without
+changing anything or reserving ids.
+
+An applied batch is exactly one undo step in both capture modes; pass
+`history: 'none'` to keep it out of undo history while preserving existing undo
+and redo entries. `source: 'agent'` records provenance only. Add
+`suggest: { author, date }` to a text step to record it as a tracked change.
+
+Paragraph ids are session keys; inserted paragraphs get Word paragraph IDs as
+typed ones do, so `saveYrsDocx` returns persisted anchors for them.
+
+### Structured export
+
+Export read-only structured JSON or Markdown with block and inline anchors and
+diagnostics.
+
+```ts
+import { exportDocxMarkdown, exportDocxStructured } from '@betteroffice/docx';
+
+const content = await exportDocxStructured(bytes, {
+  revisionView: 'accepted',
+  stories: ['body', 'headers', 'footers'],
+});
+for (const block of content.stories[0].blocks) {
+  if (block.kind === 'heading') console.log(block.heading.outlineLevel, block.anchor);
+}
+const { markdown, anchors } = await exportDocxMarkdown(bytes, { revisionView: 'markup' });
+```
+
+On a live session, `session.exportStructured(options)` and
+`session.exportMarkdown(options)` return `{ ok: true, version, content }` from one
+read of the committed state: anchors resolve against that version, and nothing is
+committed, flushed or published. Bytes exports and `renderDocxMarkdown(content)`
+return snapshot content and throw `DocxExportError` for unusable options. A
+refusal's `failure` is `{ code, target, message }`, with `target: null` when it
+concerns no anchor; `unsupported` means the session holds no document content.
+`session.headings(story)` lists a story's headings classified the same way; the
+legacy `collectHeadings` tree walker from `@betteroffice/docx/utils` is deprecated
+in its favour.
+
+Content is `schemaVersion: 1`: ordered stories (`body` by default; `headers`,
+`footers`, `footnotes`, `endnotes` and `comments` only when selected), each a list
+of paragraphs, headings (outline level and whether it came from direct formatting,
+the style chain, document defaults or a `HeadingN` style id), list items (numbering
+format and the rendered marker, counted as Word counts them: numbering instances of
+one abstract definition continue each other unless one overrides a start and so
+begins its own list, levels begin at `w:start` and restart as `w:lvlRestart` says),
+tables on the source grid with spans, skipped grid columns and vertical-merge
+continuations, content controls, section breaks, and placeholders naming the
+source element of other content. Inlines cover text, tabs, line,
+page and column breaks where the source has them, note and comment references,
+fields with their cached result in result order, hyperlinks and nested fields
+included, all anchored to the field (a numeric field's result
+blocks stay inside the field), images (alt text and the relationship of the part
+that owns them) and inline controls. A header or footer part
+referenced through several relationships is one story with every section that
+uses it while the copies hold the same content, and one story per copy with a
+diagnostic once they differ. `revisionView` is required: `accepted` and
+`original` project pending revisions like `readParagraphs`, and `markup` keeps
+both with `revisions` attribution on each inline, moves as `moveFrom` and
+`moveTo`. Other revision history exports as an anchored `unsupported`
+placeholder with an `unsupported-revision` diagnostic.
+
+Anchors use the batch offsets and session keys: a paragraph anchor's `paraId` is the
+batch target key, and a range is paragraph-local UTF-16 in the view it
+names, one U+FFFC per atom, the same shape the edit batches take; ranges from a
+session export address the version it returned. Content without a session
+location (comment bodies, omitted raw XML) carries a `sourcePart` anchor: the
+part, its SHA-256, and element-child ordinals into its XML. Content with no
+location of its own carries `{ kind: 'unlocated', story, reason }`: the reason is
+`duplicate-paragraph-id` (a paragraph whose Word paragraph ID repeats an earlier one
+opens with a session key of its own, and edits and merges repair a key two paragraphs
+share, so only shared state written outside the engine has it), `story-too-large`,
+`missing-story` or
+`provenance-unavailable`. Comment metadata reads
+the session's comment store once a field has been written there, and the source
+until then. Ids are deterministic export-tree paths, and a bytes export is
+identical across runs. Exports admit one top-level block at a time, charge text before copying it, and stop at
+`maxBlocks` (10,000 by default, every nested block counted) or `maxBytes`
+(8,388,608 by default, on the compact JSON) at a whole top-level block, set
+`truncated`, and end with a `truncated` diagnostic; the prefix already admitted is
+kept, and a larger `maxBytes` never keeps fewer blocks. Of a story longer than
+four units per remaining byte beyond one million, only the leading paragraphs
+within that bound are read: those that fit are kept, then the export stops and says
+so. A comment body, field payload, shape or table cell past the bound is not read
+at all. Markdown keeps story separators, headings, lists, tables (pipe tables, or
+entity-escaped HTML, nested where needed, for merged or multi-block cells), attributed insertions and deletions, and a
+`<!-- docx-export:N -->` marker per block, nested ones included, mapped to its
+anchor in `anchors`. Only http, https, mailto and internal-anchor targets are linked,
+judged after entity and percent decoding, and `&` in a target is written `&amp;`; document text, titles and alt text never keep a
+line break or unescaped HTML.
+
+### Page fragments
+
+A paged export attaches a page map to the structured content: the physical page,
+section and displayed page label showing each block and inline, and the body,
+header, footer or note occurrence it sits in.
+
+```ts
+import { exportDocxStructuredWithPages, renderDocxMarkdownWithPages } from '@betteroffice/docx';
+
+const paged = await exportDocxStructuredWithPages(
+  bytes,
+  { revisionView: 'markup', stories: ['body', 'headers', 'footnotes'], includeGeometry: true },
+  { fonts: [{ key: 'sans', data: fontBase64 }], defaultChain: ['sans'] }
+);
+paged.layout.pages; // pageIndex, displayedLabel, sectionIndex, parityFiller, size
+paged.layout.fragments; // pageIndex, occurrenceId, nodeId, slice, continuation flags, geometry
+const { markdown } = await renderDocxMarkdownWithPages(paged, { pageMarkers: true });
+```
+
+`exportDocxStructuredWithPages` opens the bytes in a private session, registers
+exactly the fonts it is given, as base64 data, in a measurement font store of its
+own (a requirement `family|bold|italic` takes the chain named by its key, else by
+its lowercase family, else `defaultChain`; nothing is looked up on the system and
+no editor's fonts change), lays out every section, header, footer and note, and
+exports from that one state. Its options are plain JSON: `measurementDefaults`
+(`fontFamily`, `fontSize`), `renderEnvironment` (`showHiddenText`,
+`defaultTabStopTwips`) and `compatibility`, all fingerprinted in the map's
+provenance. A requirement left with no font, including the `measurementDefaults`
+family text naming none falls back to, or any text measured with stand-in metrics
+is refused as `layout-unavailable`, as is a live layout whose font store was
+cleared or added to since.
+The snapshot map is deterministic for the same bytes, fonts and options and
+carries no session token. `session.exportStructuredWithPages(options)` reads the
+region layout a session retains and lays nothing out, flushes nothing and loads no
+font; the layout must have lowered the current version from the session's own
+stories, with section, settings and note metadata that describe it and a
+registered font for every requirement. Its map carries `documentVersion` and a
+`layoutVersion` to pass back as `expectLayoutVersion`; its references describe the
+authoritative layout of that version, which a later edit may supersede before it is
+painted.
+
+`pageIndex` counts physical pages from zero, blank parity pages included, while
+`displayedNumber`/`displayedLabel` follow the section's PAGE numbering (restarts,
+continuation and Roman or letter formats). A header or footer part stays one exported story with an occurrence
+on every page showing it; a note has an occurrence where its note area is, which
+may differ from its reference's page. Text slices are ranges in the export's own
+offsets, split where the node, paragraph, view or page changes; atoms (fields,
+controls, images, note marks, breaks) are sliced whole, and one split across
+pages carries `partial` and an `anchor-only` diagnostic. Table
+fragments list their row window with `continuedFromPrevious`, `continuedOnNext`
+and `repeatedHeader`, and each cell paragraph has fragments of its own for the lines
+its cell shows (a line the cell cuts through is listed with a `clipped-content`
+diagnostic). Pages are
+laid out with revision markup, so while a laid-out story holds pending revisions a
+paged export reads the `markup` view, and `accepted` or `original` return
+`unsupported-revision-layout`. The other refusal codes are `stale-document`,
+`stale-layout` (stale section, settings or note metadata, fonts, options or
+`expectLayoutVersion`), `layout-unavailable`, `layout-not-converged` and
+`unsupported`.
+Geometry is off by default; rectangles are unzoomed CSS pixels (96 per inch) from
+the physical page's top-left corner. `maxFragments` (100,000 by default) and
+`maxLayoutBytes` bound the map separately and mark it `truncated`; mapping stops a
+page past the limit, so a truncated map leaves out the diagnostics of later pages
+and of paragraphs no page shows. With
+`pageMarkers`, Markdown follows each block marker with
+`<!-- docx-pages: 0=i 1=ii -->` (labels percent-encoded) and writes no page break
+into the text; a map from other content is refused. The map is `schemaVersion: 1`,
+versioned apart from the content: additive fields keep the version, and a change
+existing readers would misread bumps it.
+
+### Content controls
+
+List a document's content controls and fill its plain- and rich-text controls in
+one version-checked batch.
+
+```ts
+const read = session.listContentControls();
+if (!read.ok) throw new Error(read.failure.message);
+const name = read.content.controls.find((control) => control.tag === 'customer.name')!;
+
+const result = session.applyEdits({
+  expectVersion: read.version,
+  steps: [
+    { op: 'setContentControlText', target: { kind: 'id', controlId: name.controlId }, text: 'Ada Lovelace' },
+    { op: 'setContentControlText', target: { kind: 'tag', tag: 'customer.address' }, text: '12 Example Street\nLondon' },
+  ],
+});
+```
+
+Controls come in document order (body, headers, footers, footnotes, endnotes,
+comments; a control before the controls inside it), each with the structured
+export's control metadata (`controlId`, `ooxmlId`, `controlType`, `tag`, `alias`,
+`lock`, `showingPlaceholder`, `dataBound`) plus `placement`, `anchor`,
+`parentControlId`, `value` (its text with tabs as `\t` and line and paragraph
+breaks as LF, or `unavailable` with a reason), `multiLine` and `effectiveLock`,
+which folds in the locks of the controls containing it. `stories` narrows the read
+to some categories; `maxControls` (10,000) and `maxBytes` (8,388,608) refuse with
+`limit-exceeded` rather than returning part of the list, and `complete: false`
+includes coverage diagnostics. Tags, aliases and
+`ooxmlId`s match exactly and case-sensitively, and `findContentControls` returns
+every match. `listDocxContentControls(bytes)` and
+`findDocxContentControls(bytes, query)` read bytes without a session and throw
+`DocxContentControlsError` for refused options. Concurrent fills from
+collaborators resolve last-writer-wins for an inline control and merge like
+concurrent typing for a block control.
+
+A step's `target` is `{ kind: 'id', controlId }`, `{ kind: 'tag', tag }` or
+`{ kind: 'ooxmlId', ooxmlId }`. `controlId` is a locator scoped to the
+version or snapshot it was read at; list again after a version change. Tags are the template author's names for
+controls. `ooxmlId` is the control's authored `w:id`, the identity that survives
+save and reopen. A tag or `ooxmlId` write searches every story regardless of read
+filters and needs exactly one control in the document to carry it.
+
+`setContentControlText` replaces the content of a plain- or rich-text control
+with plain text and clears its placeholder flag everywhere it is recorded,
+leaving tags, aliases, ids, bindings and every other property as captured. CRLF
+becomes LF; LF is a line break, except in a rich-text block control, where it
+starts a paragraph: surviving paragraphs keep their ids and properties and new
+ones take the first paragraph's style defaults. A plain-text control accepts LF
+only when its `w:text` sets `w:multiLine` and keeps its lines in one paragraph.
+The text takes the formatting of the control's first text run, or the control's
+own run properties while it shows its placeholder. Equal text is a no-op unless
+the placeholder still shows or a plain-text control holds several paragraphs,
+which the fill joins into one. Refusals
+carry the batch code and a `reason`: `missing-control`, `missing-tag` or
+`missing-ooxml-id`, `ambiguous-control-id`, `ambiguous-tag` or
+`ambiguous-ooxml-id`, `content-locked`, `bound-control`,
+`unsupported-control-type`, `unsupported-children` (content other than text,
+tabs and line breaks, such as bookmarks, fields or tables), `nested-controls`,
+`unknown-lock`, `unsupported-suggestion`, `provenance-unavailable` (the session
+was not opened from DOCX bytes), `unsupported-story` (a control kept only in
+source XML, such as a comment body), `multiline-not-allowed` and `invalid-text`.
+Checkbox, dropdown and date controls keep `setContentControlValue`; a
+string passed to it fills a text control through the same step, and
+`clearContentControlValue` never erases a text control's text.
+
+### Compare documents into tracked changes
+
+Compare an original and a revised DOCX and get back the original with the
+body text differences as tracked insertions and deletions, attributed to the
+author and date you pass:
+
+```ts
+import { compareDocx } from '@betteroffice/docx';
+
+const result = await compareDocx(original, revised, {
+  author: 'Contract review',
+  date: '2024-05-06T09:30:00+02:00',
+  granularity: 'word',
+  unsupported: 'fail',
+});
+if (result.ok) {
+  for (const change of result.changes) console.log(change.id, change.kind, change.revised.text);
+} else {
+  console.warn(result.diagnostics.map((diagnostic) => diagnostic.code));
+}
+```
+
+`compareDocx` compares the text of body paragraphs whose structure is unchanged. Both
+packages are inspected in full before anything is authored, and any blocking
+difference refuses the comparison with `{ ok: false, diagnostics }`; no partial
+redline is ever returned. `unsupported: 'report'` keeps inspecting and returns
+every diagnostic, bounded by `limits.maxDiagnostics`. Blocking codes are
+`invalid-options`, `invalid-docx`, `existing-revisions` (anywhere, headers and
+property revisions included), `paragraph-insertion`, `paragraph-deletion`,
+`paragraph-move`, `ambiguous-alignment`, `table-change`, `structure-change`,
+`field-change`, `object-change`, `content-control-change`, `formatting-change`,
+`unsupported-content` and `unsupported-formatting` (a changed paragraph holding
+content, or run properties, that edits cannot carry, such as fields,
+hyperlinks, bookmarks, objects, page breaks, patterned shading or `w:lang`),
+`out-of-scope-change` (headers, footers, notes, comments), `opaque-part-change`,
+`provenance-unavailable`, `limit-exceeded`, `diagnostics-truncated`,
+`batch-refused`, `serialization-failed` and `roundtrip-mismatch`.
+`metadata-difference` (informational: modified dates, revision-session ids and
+document statistics, kept from the original) and `ambiguous-identity` (a
+warning: repeated paragraph ids, so changes are addressed by position) accompany
+a result. Every part whose content type or content is XML is scanned for
+revisions, and wrappers such as custom XML elements, body-level markers and
+every part must match exactly; an XML-typed part that cannot be read refuses the
+comparison.
+
+Paragraphs are aligned conservatively: text unique to one paragraph on each side
+anchors the alignment, crossing anchors are moves, one paragraph against one
+between anchors is a replacement, and several need shared words and exactly one
+best correspondence. Clearing a paragraph's text is a deletion; the paragraph
+mark stays. Differences are reported by Unicode word, keeping punctuation and
+whitespace tokens, or with `granularity: 'char'` by grapheme cluster. Each
+change is one tracked replacement: deleted text keeps its formatting and
+inserted text takes the revised formatting. Changes are ordered by original
+position, `id` is `change-0`, `change-1` and so on, and their spans address the
+inputs by part, SHA-256 and element-child path with paragraph-local UTF-16
+offsets. `date` must be RFC 3339 with an explicit offset and is recorded in UTC;
+the clock is never read. `author` must not be blank.
+
+Only the changed paragraphs' content is rewritten; their start tags and
+properties, every other paragraph and every other part keep the original's
+bytes, and identical inputs return the original bytes. Rewritten runs carry the
+session's formatting vocabulary, so run properties a style supplies are written
+as direct formatting, and complex-script fonts, sizes, bold and italic are
+written only as the source states them. The result is reopened and checked
+against both inputs before it is returned, with each run's effective formatting
+read from the XML, style toggles such as bold combined across every level of a
+style's `basedOn` chain; a difference refuses with `roundtrip-mismatch`.
+Defaults, which are also the ceilings: 32 MiB per input, 128 MiB inflated,
+10,000 paragraphs per input and 1,048,576 UTF-16 units of text in both inputs,
+counted across every story while the parts are read, 250,000 alignment cells,
+4,000,000 diff cells, 128 changes, 256 diagnostics, 64 MiB of staged state,
+8 MiB of result JSON without the output package (at least 1 KiB) and a 64 MiB
+output, the no-op included.
+Review in BetterOffice is tested.
+
+### Editor plugin contract (deprecated)
+
+`@betteroffice/docx/plugin-api` keeps its geometry and sidebar building blocks:
+`RenderedDomContext`, `PositionCoordinates`, `SidebarItem`,
+`createRenderedDomContext`, `createCanvasHostProjector` and
+`resolveItemPositions`. The snapshot-based `EditorPluginCore`,
+`PluginPanelProps`, `PanelConfig` and `SidebarItemContext` are deprecated: they
+pass serialized `Document` snapshots and have no host that manages their
+lifecycle. Host plugins for the React editor use `defineDocxPlugin` and the
+`plugins` prop of
+[`@betteroffice/docx-react`](https://www.npmjs.com/package/@betteroffice/docx-react),
+which provide versioned reads, granted commands and edit batches, lifecycle
+events and cleanup.
+
+### Reanchor an existing comment
+
+`session.setCommentRanges(commentId, ranges)` replaces only the sticky anchors of
+an existing comment. The id, author, date, body, reply relationship and resolution
+state remain intact. Ranges use the same paragraph locations as `addComment`;
+one range may span paragraphs, and separate ranges may address different stories.
+
+Every range must be non-empty, ordered, and within existing paragraphs. An empty
+list, unknown comment/story/paragraph, or invalid offset throws before any content
+changes. The host supplies the surviving text's new range.
+
+If replacement removes all commented text, the host must explicitly choose a new
+non-empty range or handle the comment's removal. Rejected reanchoring leaves the
+comment unchanged and does not roll back a text replacement already performed.
+
+`saveYrsDocx()` writes the current ranges under the comment's own ID, with its
+author, date, body, replies and resolution.
+
+Reanchoring joins the current local undo capture, so an immediate replacement and
+reanchor can undo together. Comment edits participate in the session's history;
+undoing comment changes conservatively invalidates all stories for saved anchors.
+
+The undo manager retains comment item boundaries with their undo/redo entries so
+anchors inside replaced text survive repeated history traversal with Yrs 0.27.
+Discarding history releases its bookkeeping; undo/redo traverses a local snapshot
+when those boundaries need restoration.
+
+### External drop positions
+
+`RenderedDomContext.getPositionAtPoint(clientX, clientY)` queries the same canvas
+hit testing used for the caret. Pass viewport coordinates, such as a drop event's
+`clientX` and `clientY`. Page scroll and CSS zoom are resolved from the live page
+geometry. The query never changes selection or focus.
+
+The result contains `position`, `pageIndex`, and `region`. Header/footer hits also
+carry `rId`; footnote/endnote hits carry `noteId`. Positions are local to that
+region's display stream in the layout the context renders, and shift with every
+edit.
+
+In React, `editorRef.getPositionAtPoint(clientX, clientY)` runs the same query and
+adds `version` and `target`: the collapsed accepted-view range at the point, keyed
+by session paragraph keys, in the body, header, footer, note or table cell story
+the point is in. Use it as a text step's target with `expectVersion: version`:
+
+```ts
+const hit = editorRef.current!.getPositionAtPoint(event.clientX, event.clientY);
+if (hit) {
+  await editorRef.current!.applyEdits({
+    expectVersion: hit.version,
+    steps: [{ op: 'insertText', target: hit.target, at: 'start', text: '{{customer.name}}' }],
+  });
+}
+```
+
+It returns `null` while typed or composed input is pending and until the painted
+pages show the current version (retry after `flushPendingInput()` or on the next
+frame), and a batch applied after further typing refuses with `stale-version`, so a
+drop never lands at a shifted position. Plugins get the same query as
+`context.geometry.getPositionAtPoint`, with the layout's `layoutId`. The lower-level
+`editorRef.getEditorRef()?.displayPositionToYrsLoc(hit)` maps a hit to its live
+`YrsLoc` (offsets that count text a pending deletion hides) without the version
+check; passing a number to it retains body mapping.
+
+Text runs and their editable content boxes are accepted. Page margins, images,
+page gaps, points outside pages, and queries without ready canvas geometry return
+`null`.

package/dist/{chunk-JHJLG4I6.mjs → chunk-5B4VMUXM.mjs}

@@ -1,4 +1,4 @@
-import {d as d$1}from'./chunk-6LQJAKOC.mjs';import {a,b as b$1}from'./chunk-HLDJMU3R.mjs';import {a as a$1}from'./chunk-ACGKK7IB.mjs';async function pe(n){if(n instanceof ArrayBuffer)return n;if(n instanceof Uint8Array){let e=new ArrayBuffer(n.byteLength);return new Uint8Array(e).set(n),e}if(n instanceof Blob)return n.arrayBuffer();throw new TypeError(`Unsupported DocxInput type: ${typeof n}`)}function P(n){let e=n.replace(/[^0-9a-fA-F]/g,"");if(e.length!==32)return null;let t=new Uint8Array(16);for(let r=0;r<16;r++){let i=Number.parseInt(e.slice(r*2,r*2+2),16);if(Number.isNaN(i))return null;t[r]=i;}let o=new Uint8Array(16);for(let r=0;r<16;r++)o[r]=t[15-r];return o}function B(n){return n?P(n)!==null:false}function v(n,e){let t=P(e);if(!t)throw new Error(`Invalid embedded-font key: "${e}"`);let o=new Uint8Array(n.slice(0)),r=Math.min(32,o.length);for(let i=0;i<r;i++)o[i]^=t[i%16];return o.buffer}var W={calibri:{googleFont:"Carlito",category:"sans-serif",fallbackStack:["Calibri","Carlito","Arial","Helvetica","sans-serif"],singleLineRatio:1.2207},cambria:{googleFont:"Caladea",category:"serif",fallbackStack:["Cambria","Caladea","Georgia","serif"],singleLineRatio:1.2676},arial:{googleFont:"Arimo",category:"sans-serif",fallbackStack:["Arial","Arimo","Helvetica","sans-serif"],singleLineRatio:1.1172},"times new roman":{googleFont:"Tinos",category:"serif",fallbackStack:["Times New Roman","Tinos","Times","serif"],singleLineRatio:1.1074},"courier new":{googleFont:"Cousine",category:"monospace",fallbackStack:["Courier New","Cousine","Courier","monospace"],singleLineRatio:1.1328},georgia:{googleFont:"Tinos",category:"serif",fallbackStack:["Georgia","Tinos","Times New Roman","serif"],singleLineRatio:1.1362},verdana:{googleFont:"Open Sans",category:"sans-serif",fallbackStack:["Verdana","Open Sans","Arial","sans-serif"],singleLineRatio:1.2153},tahoma:{googleFont:"Open Sans",category:"sans-serif",fallbackStack:["Tahoma","Open Sans","Arial","sans-serif"],singleLineRatio:1.2075},"trebuchet ms":{googleFont:"Fira Sans",category:"sans-serif",fallbackStack:["Trebuchet MS","Fira Sans","Arial","sans-serif"],singleLineRatio:1.1431},"comic sans ms":{googleFont:"Comic Neue",category:"cursive",fallbackStack:["Comic Sans MS","Comic Neue","cursive"],singleLineRatio:1.3936},impact:{googleFont:"Anton",category:"sans-serif",fallbackStack:["Impact","Anton","Arial Black","sans-serif"],singleLineRatio:1.2197},"palatino linotype":{googleFont:"EB Garamond",category:"serif",fallbackStack:["Palatino Linotype","EB Garamond","Palatino","Georgia","serif"],singleLineRatio:1.0259},"book antiqua":{googleFont:"EB Garamond",category:"serif",fallbackStack:["Book Antiqua","EB Garamond","Palatino","Georgia","serif"],singleLineRatio:1.0259},garamond:{googleFont:"EB Garamond",category:"serif",fallbackStack:["Garamond","EB Garamond","Georgia","serif"],singleLineRatio:1.068},"century gothic":{googleFont:"Questrial",category:"sans-serif",fallbackStack:["Century Gothic","Questrial","Arial","sans-serif"],singleLineRatio:1.1611},"lucida sans":{googleFont:"Open Sans",category:"sans-serif",fallbackStack:["Lucida Sans","Open Sans","Arial","sans-serif"],singleLineRatio:1.1655},"lucida console":{googleFont:"Cousine",category:"monospace",fallbackStack:["Lucida Console","Cousine","Courier New","monospace"],singleLineRatio:1.1387},consolas:{googleFont:"Inconsolata",category:"monospace",fallbackStack:["Consolas","Inconsolata","Cousine","Courier New","monospace"],singleLineRatio:1.1626},"ms mincho":{googleFont:"Noto Serif JP",category:"serif",fallbackStack:["MS Mincho","Noto Serif JP","serif"],singleLineRatio:1.15},"\uFF4D\uFF53 \u660E\u671D":{googleFont:"Noto Serif JP",category:"serif",fallbackStack:["MS Mincho","\uFF2D\uFF33 \u660E\u671D","Noto Serif JP","serif"],singleLineRatio:1.15},"\uFF4D\uFF53 \uFF50\u660E\u671D":{googleFont:"Noto Serif JP",category:"serif",fallbackStack:["MS PMincho","\uFF2D\uFF33 \uFF30\u660E\u671D","Noto Serif JP","serif"],singleLineRatio:1.15},"ms gothic":{googleFont:"Noto Sans JP",category:"sans-serif",fallbackStack:["MS Gothic","Noto Sans JP","sans-serif"],singleLineRatio:1.15},"\uFF4D\uFF53 \u30B4\u30B7\u30C3\u30AF":{googleFont:"Noto Sans JP",category:"sans-serif",fallbackStack:["MS Gothic","\uFF2D\uFF33 \u30B4\u30B7\u30C3\u30AF","Noto Sans JP","sans-serif"],singleLineRatio:1.15},"\uFF4D\uFF53 \uFF50\u30B4\u30B7\u30C3\u30AF":{googleFont:"Noto Sans JP",category:"sans-serif",fallbackStack:["MS PGothic","\uFF2D\uFF33 \uFF30\u30B4\u30B7\u30C3\u30AF","Noto Sans JP","sans-serif"],singleLineRatio:1.15},simhei:{googleFont:"Noto Sans SC",category:"sans-serif",fallbackStack:["SimHei","Noto Sans SC","sans-serif"],singleLineRatio:1.15},simsun:{googleFont:"Noto Serif SC",category:"serif",fallbackStack:["SimSun","Noto Serif SC","serif"],singleLineRatio:1.15},"malgun gothic":{googleFont:"Noto Sans KR",category:"sans-serif",fallbackStack:["Malgun Gothic","Noto Sans KR","sans-serif"],singleLineRatio:1.15},\u5B8B\u4F53:{googleFont:"Noto Serif SC",category:"serif",fallbackStack:["SimSun","\u5B8B\u4F53","Noto Serif SC","serif"],singleLineRatio:1.15},\u9ED1\u4F53:{googleFont:"Noto Sans SC",category:"sans-serif",fallbackStack:["SimHei","\u9ED1\u4F53","Noto Sans SC","sans-serif"],singleLineRatio:1.15},\u5FAE\u8F6F\u96C5\u9ED1:{googleFont:"Noto Sans SC",category:"sans-serif",fallbackStack:["Microsoft YaHei","\u5FAE\u8F6F\u96C5\u9ED1","Noto Sans SC","sans-serif"],singleLineRatio:1.15},\u7B49\u7EBF:{googleFont:"Noto Sans SC",category:"sans-serif",fallbackStack:["DengXian","\u7B49\u7EBF","Noto Sans SC","sans-serif"],singleLineRatio:1.15},\u4EFF\u5B8B:{googleFont:"Noto Serif SC",category:"serif",fallbackStack:["FangSong","\u4EFF\u5B8B","Noto Serif SC","serif"],singleLineRatio:1.15},\u6977\u4F53:{googleFont:"Noto Serif SC",category:"serif",fallbackStack:["KaiTi","\u6977\u4F53","Noto Serif SC","serif"],singleLineRatio:1.15},\u65B0\u7D30\u660E\u9AD4:{googleFont:"Noto Serif TC",category:"serif",fallbackStack:["PMingLiU","\u65B0\u7D30\u660E\u9AD4","Noto Serif TC","serif"],singleLineRatio:1.15},\u7D30\u660E\u9AD4:{googleFont:"Noto Serif TC",category:"serif",fallbackStack:["MingLiU","\u7D30\u660E\u9AD4","Noto Serif TC","serif"],singleLineRatio:1.15},\u5FAE\u8EDF\u6B63\u9ED1\u9AD4:{googleFont:"Noto Sans TC",category:"sans-serif",fallbackStack:["Microsoft JhengHei","\u5FAE\u8EDF\u6B63\u9ED1\u9AD4","Noto Sans TC","sans-serif"],singleLineRatio:1.15},\u6A19\u6977\u9AD4:{googleFont:"Noto Serif TC",category:"serif",fallbackStack:["DFKai-SB","\u6A19\u6977\u9AD4","Noto Serif TC","serif"],singleLineRatio:1.15},"\uB9D1\uC740 \uACE0\uB515":{googleFont:"Noto Sans KR",category:"sans-serif",fallbackStack:["Malgun Gothic","\uB9D1\uC740 \uACE0\uB515","Noto Sans KR","sans-serif"],singleLineRatio:1.15},\uAD74\uB9BC:{googleFont:"Noto Sans KR",category:"sans-serif",fallbackStack:["Gulim","\uAD74\uB9BC","Noto Sans KR","sans-serif"],singleLineRatio:1.15},\uB3CB\uC6C0:{googleFont:"Noto Sans KR",category:"sans-serif",fallbackStack:["Dotum","\uB3CB\uC6C0","Noto Sans KR","sans-serif"],singleLineRatio:1.15},\uBC14\uD0D5:{googleFont:"Noto Serif KR",category:"serif",fallbackStack:["Batang","\uBC14\uD0D5","Noto Serif KR","serif"],singleLineRatio:1.15},\uAD81\uC11C:{googleFont:"Noto Serif KR",category:"serif",fallbackStack:["Gungsuh","\uAD81\uC11C","Noto Serif KR","serif"],singleLineRatio:1.15}},q={"sans-serif":"Arial, Helvetica, sans-serif",serif:"Times New Roman, Times, serif",monospace:"Courier New, Courier, monospace",cursive:"cursive",fantasy:"fantasy","system-ui":"system-ui, sans-serif"};function J(n){let e=n.toLowerCase();return e.includes("mono")||e.includes("courier")||e.includes("consolas")||e.includes("console")||e.includes("code")||e.includes("terminal")?"monospace":e.includes("times")||e.includes("georgia")||e.includes("garamond")||e.includes("palatino")||e.includes("baskerville")||e.includes("bodoni")||e.includes("cambria")||e.includes("mincho")||e.includes("\u660E\u671D")||e.includes("\u660E\u9AD4")||e.includes("\u5B8B")||e.includes("ming")||e.includes("song")||e.includes("serif")?"serif":e.includes("script")||e.includes("cursive")||e.includes("comic")||e.includes("brush")||e.includes("hand")?"cursive":"sans-serif"}var Y={"microsoft yahei":"\u5FAE\u8F6F\u96C5\u9ED1",dengxian:"\u7B49\u7EBF",fangsong:"\u4EFF\u5B8B",kaiti:"\u6977\u4F53",pmingliu:"\u65B0\u7D30\u660E\u9AD4",mingliu:"\u7D30\u660E\u9AD4","microsoft jhenghei":"\u5FAE\u8EDF\u6B63\u9ED1\u9AD4","dfkai-sb":"\u6A19\u6977\u9AD4",gulim:"\uAD74\uB9BC",dotum:"\uB3CB\uC6C0",batang:"\uBC14\uD0D5",gungsuh:"\uAD81\uC11C",meiryo:"ms gothic",\u30E1\u30A4\u30EA\u30AA:"ms gothic","yu gothic":"ms gothic",\u6E38\u30B4\u30B7\u30C3\u30AF:"ms gothic","yu mincho":"ms mincho",\u6E38\u660E\u671D:"ms mincho"};function O(n){let e=n.trim().toLowerCase(),t=W[Y[e]??e];if(t)return {googleFont:t.googleFont,cssFallback:t.fallbackStack.map(D).join(", "),originalFont:n,hasGoogleEquivalent:true,singleLineRatio:t.singleLineRatio};let o=J(n),r=q[o];return {googleFont:null,cssFallback:`${D(n)}, ${r}`,originalFont:n,hasGoogleEquivalent:false,singleLineRatio:1.15}}var V={"\n":"\\a ","\r":"\\d ","\f":"\\c "};function X(n){return n.replace(/["\\]/g,"\\$&").replace(/[\n\r\f]/g,e=>V[e])}function D(n){return ["serif","sans-serif","monospace","cursive","fantasy","system-ui"].includes(n.toLowerCase())?n:/[\s,'"()]/.test(n)?`"${X(n)}"`:n}var g=new Set,m=new Map,C=new Set,f=new Map,w=new Set,b=new Set,d=false,L=true,h=new Set,E=new Set;function p(n,e){let t=n instanceof Error?n.message:String(n),o=new Error(`[font] ${e}: ${t}`,{cause:n});if(b.size>0)for(let r of b)try{r(o);}catch(i){console.error("Font error subscriber threw:",i);}else console.warn(o.message);}function M(n,e="normal",t="normal"){return `${n.trim()}|${e}|${t}`}function R(n){return h.has(n)?false:E.has(n)?true:re(n)?(E.add(n),queueMicrotask(()=>T([n])),true):false}function Q(n){let e=`${n}|`,t=[];for(let[o,r]of f)o.startsWith(e)&&t.push(r);return t}function $(n,e){C.add(n),g.add(e),T([e]);}function Z(n,e=[400,700],t=["normal","italic"]){let o=encodeURIComponent(n),r=[];for(let a of t){let s=a==="italic"?1:0;for(let c of e)r.push(`${s},${c}`);}r.sort();let i=r.join(";");return `https://fonts.googleapis.com/css2?family=${o}:ital,wght@${i}&display=swap`}async function A(n,e){if(typeof document>"u")return  false;let t=n.trim();if(g.has(t))return  true;let o=m.get(t);if(o)return o;if(!e&&R(t))return  true;let r=Q(t);if(!L&&r.length===0)return  false;let i=(async()=>{d=true;try{if(r.length>0&&(await Promise.all(r),g.has(t)||!e&&R(t)))return !0;if(!L)return !1;let a=Z(t,e?.weights,e?.styles),s=document.createElement("link");return s.rel="stylesheet",s.href=a,await new Promise(l=>{let u=setTimeout(()=>l(!1),5e3);s.onload=()=>{clearTimeout(u),l(!0);},s.onerror=()=>{clearTimeout(u),l(!1);},document.head.appendChild(s);})?(await I(t,3e3),g.add(t),T([t]),!0):!1}catch(a){return p(a,`failed to load "${t}"`),false}finally{m.delete(t),m.size===0&&f.size===0&&(d=false);}})();return m.set(t,i),i}async function ee(n,e){let t=n.filter(o=>!g.has(o.trim()));t.length!==0&&await Promise.all(t.map(o=>A(o,e)));}function ne(n){let e=n.trim();return g.has(e)||E.has(e)}function Re(n){L=n;}function Ae(){return L}function Ce(){return d}function Te(){return Array.from(new Set([...g,...E]))}function Ie(n){return w.add(n),()=>{w.delete(n);}}function T(n){for(let e of w)try{e(n);}catch(t){p(t,"load callback threw");}}function _e(n){return b.add(n),()=>{b.delete(n);}}async function I(n,e){if("fonts"in document)try{let t=`400 16px "${n}"`;return await Promise.race([document.fonts.load(t),new Promise(o=>setTimeout(o,e))]),document.fonts.check(t)}catch{}return await new Promise(t=>setTimeout(t,100)),true}var F,U=new Map,te="abcdefghijklmnopqrstuvwxyz0123456789";function oe(){return F===void 0&&(F=document.createElement("canvas").getContext("2d"),F&&(F.textBaseline="top")),F}function re(n,e="sans-serif"){if(typeof document>"u")return  false;let t=oe();if(!t)return  false;let o=i=>(t.font=i,t.measureText(te).width),r=i=>{let a=U.get(i);return a===void 0&&(a=o(`72px ${i}`),U.set(i,a)),o(`72px "${n}", ${i}`)!==a};return r(e)||r(e==="sans-serif"?"serif":"sans-serif")}var ie={"<":"\\3c ",">":"\\3e ","\n":"\\a ","\r":"\\d ","\f":"\\c "},K=n=>n.replace(/["\\]/g,"\\$&").replace(/[<>\n\r\f]/g,e=>ie[e]);async function H(n,e,t){if(typeof document>"u")return  false;let o=n.trim(),r=t?.style??"normal",i=M(o,t?.weight,r);if(h.add(o),C.has(i))return  true;let a=f.get(i);if(a)return a;let s=(async()=>{d=true;try{let c=new Blob([e],{type:"font/ttf"}),l=URL.createObjectURL(c),u=document.createElement("style");return u.textContent=`
+import {d as d$1}from'./chunk-QE4ZDRKV.mjs';import {a,b as b$1}from'./chunk-HLDJMU3R.mjs';import {a as a$1}from'./chunk-ACGKK7IB.mjs';async function pe(n){if(n instanceof ArrayBuffer)return n;if(n instanceof Uint8Array){let e=new ArrayBuffer(n.byteLength);return new Uint8Array(e).set(n),e}if(n instanceof Blob)return n.arrayBuffer();throw new TypeError(`Unsupported DocxInput type: ${typeof n}`)}function P(n){let e=n.replace(/[^0-9a-fA-F]/g,"");if(e.length!==32)return null;let t=new Uint8Array(16);for(let r=0;r<16;r++){let i=Number.parseInt(e.slice(r*2,r*2+2),16);if(Number.isNaN(i))return null;t[r]=i;}let o=new Uint8Array(16);for(let r=0;r<16;r++)o[r]=t[15-r];return o}function B(n){return n?P(n)!==null:false}function v(n,e){let t=P(e);if(!t)throw new Error(`Invalid embedded-font key: "${e}"`);let o=new Uint8Array(n.slice(0)),r=Math.min(32,o.length);for(let i=0;i<r;i++)o[i]^=t[i%16];return o.buffer}var W={calibri:{googleFont:"Carlito",category:"sans-serif",fallbackStack:["Calibri","Carlito","Arial","Helvetica","sans-serif"],singleLineRatio:1.2207},cambria:{googleFont:"Caladea",category:"serif",fallbackStack:["Cambria","Caladea","Georgia","serif"],singleLineRatio:1.2676},arial:{googleFont:"Arimo",category:"sans-serif",fallbackStack:["Arial","Arimo","Helvetica","sans-serif"],singleLineRatio:1.1172},"times new roman":{googleFont:"Tinos",category:"serif",fallbackStack:["Times New Roman","Tinos","Times","serif"],singleLineRatio:1.1074},"courier new":{googleFont:"Cousine",category:"monospace",fallbackStack:["Courier New","Cousine","Courier","monospace"],singleLineRatio:1.1328},georgia:{googleFont:"Tinos",category:"serif",fallbackStack:["Georgia","Tinos","Times New Roman","serif"],singleLineRatio:1.1362},verdana:{googleFont:"Open Sans",category:"sans-serif",fallbackStack:["Verdana","Open Sans","Arial","sans-serif"],singleLineRatio:1.2153},tahoma:{googleFont:"Open Sans",category:"sans-serif",fallbackStack:["Tahoma","Open Sans","Arial","sans-serif"],singleLineRatio:1.2075},"trebuchet ms":{googleFont:"Fira Sans",category:"sans-serif",fallbackStack:["Trebuchet MS","Fira Sans","Arial","sans-serif"],singleLineRatio:1.1431},"comic sans ms":{googleFont:"Comic Neue",category:"cursive",fallbackStack:["Comic Sans MS","Comic Neue","cursive"],singleLineRatio:1.3936},impact:{googleFont:"Anton",category:"sans-serif",fallbackStack:["Impact","Anton","Arial Black","sans-serif"],singleLineRatio:1.2197},"palatino linotype":{googleFont:"EB Garamond",category:"serif",fallbackStack:["Palatino Linotype","EB Garamond","Palatino","Georgia","serif"],singleLineRatio:1.0259},"book antiqua":{googleFont:"EB Garamond",category:"serif",fallbackStack:["Book Antiqua","EB Garamond","Palatino","Georgia","serif"],singleLineRatio:1.0259},garamond:{googleFont:"EB Garamond",category:"serif",fallbackStack:["Garamond","EB Garamond","Georgia","serif"],singleLineRatio:1.068},"century gothic":{googleFont:"Questrial",category:"sans-serif",fallbackStack:["Century Gothic","Questrial","Arial","sans-serif"],singleLineRatio:1.1611},"lucida sans":{googleFont:"Open Sans",category:"sans-serif",fallbackStack:["Lucida Sans","Open Sans","Arial","sans-serif"],singleLineRatio:1.1655},"lucida console":{googleFont:"Cousine",category:"monospace",fallbackStack:["Lucida Console","Cousine","Courier New","monospace"],singleLineRatio:1.1387},consolas:{googleFont:"Inconsolata",category:"monospace",fallbackStack:["Consolas","Inconsolata","Cousine","Courier New","monospace"],singleLineRatio:1.1626},"ms mincho":{googleFont:"Noto Serif JP",category:"serif",fallbackStack:["MS Mincho","Noto Serif JP","serif"],singleLineRatio:1.15},"\uFF4D\uFF53 \u660E\u671D":{googleFont:"Noto Serif JP",category:"serif",fallbackStack:["MS Mincho","\uFF2D\uFF33 \u660E\u671D","Noto Serif JP","serif"],singleLineRatio:1.15},"\uFF4D\uFF53 \uFF50\u660E\u671D":{googleFont:"Noto Serif JP",category:"serif",fallbackStack:["MS PMincho","\uFF2D\uFF33 \uFF30\u660E\u671D","Noto Serif JP","serif"],singleLineRatio:1.15},"ms gothic":{googleFont:"Noto Sans JP",category:"sans-serif",fallbackStack:["MS Gothic","Noto Sans JP","sans-serif"],singleLineRatio:1.15},"\uFF4D\uFF53 \u30B4\u30B7\u30C3\u30AF":{googleFont:"Noto Sans JP",category:"sans-serif",fallbackStack:["MS Gothic","\uFF2D\uFF33 \u30B4\u30B7\u30C3\u30AF","Noto Sans JP","sans-serif"],singleLineRatio:1.15},"\uFF4D\uFF53 \uFF50\u30B4\u30B7\u30C3\u30AF":{googleFont:"Noto Sans JP",category:"sans-serif",fallbackStack:["MS PGothic","\uFF2D\uFF33 \uFF30\u30B4\u30B7\u30C3\u30AF","Noto Sans JP","sans-serif"],singleLineRatio:1.15},simhei:{googleFont:"Noto Sans SC",category:"sans-serif",fallbackStack:["SimHei","Noto Sans SC","sans-serif"],singleLineRatio:1.15},simsun:{googleFont:"Noto Serif SC",category:"serif",fallbackStack:["SimSun","Noto Serif SC","serif"],singleLineRatio:1.15},"malgun gothic":{googleFont:"Noto Sans KR",category:"sans-serif",fallbackStack:["Malgun Gothic","Noto Sans KR","sans-serif"],singleLineRatio:1.15},\u5B8B\u4F53:{googleFont:"Noto Serif SC",category:"serif",fallbackStack:["SimSun","\u5B8B\u4F53","Noto Serif SC","serif"],singleLineRatio:1.15},\u9ED1\u4F53:{googleFont:"Noto Sans SC",category:"sans-serif",fallbackStack:["SimHei","\u9ED1\u4F53","Noto Sans SC","sans-serif"],singleLineRatio:1.15},\u5FAE\u8F6F\u96C5\u9ED1:{googleFont:"Noto Sans SC",category:"sans-serif",fallbackStack:["Microsoft YaHei","\u5FAE\u8F6F\u96C5\u9ED1","Noto Sans SC","sans-serif"],singleLineRatio:1.15},\u7B49\u7EBF:{googleFont:"Noto Sans SC",category:"sans-serif",fallbackStack:["DengXian","\u7B49\u7EBF","Noto Sans SC","sans-serif"],singleLineRatio:1.15},\u4EFF\u5B8B:{googleFont:"Noto Serif SC",category:"serif",fallbackStack:["FangSong","\u4EFF\u5B8B","Noto Serif SC","serif"],singleLineRatio:1.15},\u6977\u4F53:{googleFont:"Noto Serif SC",category:"serif",fallbackStack:["KaiTi","\u6977\u4F53","Noto Serif SC","serif"],singleLineRatio:1.15},\u65B0\u7D30\u660E\u9AD4:{googleFont:"Noto Serif TC",category:"serif",fallbackStack:["PMingLiU","\u65B0\u7D30\u660E\u9AD4","Noto Serif TC","serif"],singleLineRatio:1.15},\u7D30\u660E\u9AD4:{googleFont:"Noto Serif TC",category:"serif",fallbackStack:["MingLiU","\u7D30\u660E\u9AD4","Noto Serif TC","serif"],singleLineRatio:1.15},\u5FAE\u8EDF\u6B63\u9ED1\u9AD4:{googleFont:"Noto Sans TC",category:"sans-serif",fallbackStack:["Microsoft JhengHei","\u5FAE\u8EDF\u6B63\u9ED1\u9AD4","Noto Sans TC","sans-serif"],singleLineRatio:1.15},\u6A19\u6977\u9AD4:{googleFont:"Noto Serif TC",category:"serif",fallbackStack:["DFKai-SB","\u6A19\u6977\u9AD4","Noto Serif TC","serif"],singleLineRatio:1.15},"\uB9D1\uC740 \uACE0\uB515":{googleFont:"Noto Sans KR",category:"sans-serif",fallbackStack:["Malgun Gothic","\uB9D1\uC740 \uACE0\uB515","Noto Sans KR","sans-serif"],singleLineRatio:1.15},\uAD74\uB9BC:{googleFont:"Noto Sans KR",category:"sans-serif",fallbackStack:["Gulim","\uAD74\uB9BC","Noto Sans KR","sans-serif"],singleLineRatio:1.15},\uB3CB\uC6C0:{googleFont:"Noto Sans KR",category:"sans-serif",fallbackStack:["Dotum","\uB3CB\uC6C0","Noto Sans KR","sans-serif"],singleLineRatio:1.15},\uBC14\uD0D5:{googleFont:"Noto Serif KR",category:"serif",fallbackStack:["Batang","\uBC14\uD0D5","Noto Serif KR","serif"],singleLineRatio:1.15},\uAD81\uC11C:{googleFont:"Noto Serif KR",category:"serif",fallbackStack:["Gungsuh","\uAD81\uC11C","Noto Serif KR","serif"],singleLineRatio:1.15}},q={"sans-serif":"Arial, Helvetica, sans-serif",serif:"Times New Roman, Times, serif",monospace:"Courier New, Courier, monospace",cursive:"cursive",fantasy:"fantasy","system-ui":"system-ui, sans-serif"};function J(n){let e=n.toLowerCase();return e.includes("mono")||e.includes("courier")||e.includes("consolas")||e.includes("console")||e.includes("code")||e.includes("terminal")?"monospace":e.includes("times")||e.includes("georgia")||e.includes("garamond")||e.includes("palatino")||e.includes("baskerville")||e.includes("bodoni")||e.includes("cambria")||e.includes("mincho")||e.includes("\u660E\u671D")||e.includes("\u660E\u9AD4")||e.includes("\u5B8B")||e.includes("ming")||e.includes("song")||e.includes("serif")?"serif":e.includes("script")||e.includes("cursive")||e.includes("comic")||e.includes("brush")||e.includes("hand")?"cursive":"sans-serif"}var Y={"microsoft yahei":"\u5FAE\u8F6F\u96C5\u9ED1",dengxian:"\u7B49\u7EBF",fangsong:"\u4EFF\u5B8B",kaiti:"\u6977\u4F53",pmingliu:"\u65B0\u7D30\u660E\u9AD4",mingliu:"\u7D30\u660E\u9AD4","microsoft jhenghei":"\u5FAE\u8EDF\u6B63\u9ED1\u9AD4","dfkai-sb":"\u6A19\u6977\u9AD4",gulim:"\uAD74\uB9BC",dotum:"\uB3CB\uC6C0",batang:"\uBC14\uD0D5",gungsuh:"\uAD81\uC11C",meiryo:"ms gothic",\u30E1\u30A4\u30EA\u30AA:"ms gothic","yu gothic":"ms gothic",\u6E38\u30B4\u30B7\u30C3\u30AF:"ms gothic","yu mincho":"ms mincho",\u6E38\u660E\u671D:"ms mincho"};function O(n){let e=n.trim().toLowerCase(),t=W[Y[e]??e];if(t)return {googleFont:t.googleFont,cssFallback:t.fallbackStack.map(D).join(", "),originalFont:n,hasGoogleEquivalent:true,singleLineRatio:t.singleLineRatio};let o=J(n),r=q[o];return {googleFont:null,cssFallback:`${D(n)}, ${r}`,originalFont:n,hasGoogleEquivalent:false,singleLineRatio:1.15}}var V={"\n":"\\a ","\r":"\\d ","\f":"\\c "};function X(n){return n.replace(/["\\]/g,"\\$&").replace(/[\n\r\f]/g,e=>V[e])}function D(n){return ["serif","sans-serif","monospace","cursive","fantasy","system-ui"].includes(n.toLowerCase())?n:/[\s,'"()]/.test(n)?`"${X(n)}"`:n}var g=new Set,m=new Map,C=new Set,f=new Map,w=new Set,b=new Set,d=false,L=true,h=new Set,E=new Set;function p(n,e){let t=n instanceof Error?n.message:String(n),o=new Error(`[font] ${e}: ${t}`,{cause:n});if(b.size>0)for(let r of b)try{r(o);}catch(i){console.error("Font error subscriber threw:",i);}else console.warn(o.message);}function M(n,e="normal",t="normal"){return `${n.trim()}|${e}|${t}`}function R(n){return h.has(n)?false:E.has(n)?true:re(n)?(E.add(n),queueMicrotask(()=>T([n])),true):false}function Q(n){let e=`${n}|`,t=[];for(let[o,r]of f)o.startsWith(e)&&t.push(r);return t}function $(n,e){C.add(n),g.add(e),T([e]);}function Z(n,e=[400,700],t=["normal","italic"]){let o=encodeURIComponent(n),r=[];for(let a of t){let s=a==="italic"?1:0;for(let c of e)r.push(`${s},${c}`);}r.sort();let i=r.join(";");return `https://fonts.googleapis.com/css2?family=${o}:ital,wght@${i}&display=swap`}async function A(n,e){if(typeof document>"u")return  false;let t=n.trim();if(g.has(t))return  true;let o=m.get(t);if(o)return o;if(!e&&R(t))return  true;let r=Q(t);if(!L&&r.length===0)return  false;let i=(async()=>{d=true;try{if(r.length>0&&(await Promise.all(r),g.has(t)||!e&&R(t)))return !0;if(!L)return !1;let a=Z(t,e?.weights,e?.styles),s=document.createElement("link");return s.rel="stylesheet",s.href=a,await new Promise(l=>{let u=setTimeout(()=>l(!1),5e3);s.onload=()=>{clearTimeout(u),l(!0);},s.onerror=()=>{clearTimeout(u),l(!1);},document.head.appendChild(s);})?(await I(t,3e3),g.add(t),T([t]),!0):!1}catch(a){return p(a,`failed to load "${t}"`),false}finally{m.delete(t),m.size===0&&f.size===0&&(d=false);}})();return m.set(t,i),i}async function ee(n,e){let t=n.filter(o=>!g.has(o.trim()));t.length!==0&&await Promise.all(t.map(o=>A(o,e)));}function ne(n){let e=n.trim();return g.has(e)||E.has(e)}function Re(n){L=n;}function Ae(){return L}function Ce(){return d}function Te(){return Array.from(new Set([...g,...E]))}function Ie(n){return w.add(n),()=>{w.delete(n);}}function T(n){for(let e of w)try{e(n);}catch(t){p(t,"load callback threw");}}function _e(n){return b.add(n),()=>{b.delete(n);}}async function I(n,e){if("fonts"in document)try{let t=`400 16px "${n}"`;return await Promise.race([document.fonts.load(t),new Promise(o=>setTimeout(o,e))]),document.fonts.check(t)}catch{}return await new Promise(t=>setTimeout(t,100)),true}var F,U=new Map,te="abcdefghijklmnopqrstuvwxyz0123456789";function oe(){return F===void 0&&(F=document.createElement("canvas").getContext("2d"),F&&(F.textBaseline="top")),F}function re(n,e="sans-serif"){if(typeof document>"u")return  false;let t=oe();if(!t)return  false;let o=i=>(t.font=i,t.measureText(te).width),r=i=>{let a=U.get(i);return a===void 0&&(a=o(`72px ${i}`),U.set(i,a)),o(`72px "${n}", ${i}`)!==a};return r(e)||r(e==="sans-serif"?"serif":"sans-serif")}var ie={"<":"\\3c ",">":"\\3e ","\n":"\\a ","\r":"\\d ","\f":"\\c "},K=n=>n.replace(/["\\]/g,"\\$&").replace(/[<>\n\r\f]/g,e=>ie[e]);async function H(n,e,t){if(typeof document>"u")return  false;let o=n.trim(),r=t?.style??"normal",i=M(o,t?.weight,r);if(h.add(o),C.has(i))return  true;let a=f.get(i);if(a)return a;let s=(async()=>{d=true;try{let c=new Blob([e],{type:"font/ttf"}),l=URL.createObjectURL(c),u=document.createElement("style");return u.textContent=`
       @font-face {
         font-family: "${K(o)}";
         src: url(${l}) format('truetype');