@stesura/core/helpers

Runs callback for every type (no short-circuit); true if any returned true.

Word’s “At least” pt as a line-height multiplier. Word lays each line at the larger of pt and the line’s single line (checked over COM); the paragraph’s main run (most characters) stands in for its lines. 1 when pt is within that run’s single line, the common case (corpus: ~80% of “At least” paragraphs).

A ChangeSet token encoder that also distinguishes the given attrs.

The default encoder tokenizes a node by type name alone, so two same-type atoms with different attrs look identical. Pasting a copy of a range back over part of itself then diffs as unchanged and the replaced node is never reported (MT-16: a deleted comment_open went unreported, orphaning its close).

Use for atoms whose attrs ARE their identity. Nodes without any of these attrs set encode exactly as the default.

True when the block holds no text beyond whitespace or a lone zero-width space. Not an emptiness check: a block holding only an atom (image, page number) answers true, which is what numbering wants when skipping blank lines. Text carrying hidden (pending deletion) doesn’t count: accepted, it’s gone.

Whether the selection can be wrapped in an inline node: each range at one depth, no boundary nodes inside.

Ranges of after that may hold nodes differing from before: a superset, found by comparing the two trees instead of mapping steps, so its cost is independent of how many steps produced after (CORE-156).

ProseMirror nodes are persistent: an unchanged subtree is the same object in both docs. Per node pair:

• same object: skipped;
• different markup (type, attrs, marks): the whole new node, without recursing, since an attr-only change has identical content;
• same markup: its children are compared, unless it is a textblock or a leaf, which is reported whole;
• different doc attrs: the whole document.

Ranges are disjoint and in document order. An attr set to its current value still makes a new node and is reported; callers re-derive idempotently.

Replaces the view’s document content with the schema’s minimal valid content.

Moves content into another Schema instance (e.g. main editor → sub-editor) via a JSON round trip.

Multi-node content converts PER NODE: a child the target schema rejects is dropped alone. All-or-nothing showed an empty sub-editor over a non-empty region, and every inner edit after that forwarded against divergent coordinates.

A state over doc for running a derivation written against EditorState on a doc that isn’t loaded. It carries only the stylesheet plugin, whose state resolves doc’s own sheet; without an editor id, the other helpers read the doc instead of the editor’s stores.

Builds a node or fragment from JSON or an HTML string. Node/Fragment input is returned as is. Invalid content warns and yields empty content, or throws when errorOnInvalidContent is set.

Finds the first textblock node type in a content match that has no required attributes.

A range in the NEW document, from and to on node boundaries.

Returns true if any of the transactions modified the document.

docNodeIsEmpty for state.doc.

Whether doc is missing, has no children, or holds a single empty textblock. Use when you hold a doc rather than a state, e.g. a submitted comment body.

Parses an HTML string into an HTMLElement, stripping excess whitespace.

Emit an event to the installed profiler; no-op when none is installed.

Whether ranges are many enough, or cover enough of doc, that a whole-doc pass is cheaper than one pass per range: over 200 ranges or a quarter of the doc (measured on a 355-page document, docs/partially-executed/large-docx-import-perf-plan.md).

Returns a copy of fragment with shouldRemove nodes dropped (at any depth) and transform applied to every surviving node, parents included (MT-13). Children are processed first, so transform sees already-filtered content.

pos is the offset within the node’s OWN parent fragment, not a document position.

Nodes matching predicate within range. A collapsed range checks only the node at from; otherwise the walk is nodesBetween, so ancestors overlapping the range are visited too.

The LINE_HEIGHTS entry a line height shows as, or undefined (an off-list or “Xpt” value).

Finds the first node matching a predicate in the document tree.

Recursively finds all nodes in the document tree matching a predicate.

Steps from pos in direction while the adjacent character is a word character; returns where it stopped.

Calls back with every node (descendants included) inside range and its ABSOLUTE document position.

Walks range.parent, not $from.node(): for a multi-block range the latter is the first block rather than the shared parent.

Nodes added or removed across transactions, found by a ChangeSet diff. Exits early, without a ChangeSet, when no transaction changed the doc or (with skipSimpleTextTransactions, default true) all are plain typing.

Gets node or mark attributes by type or name at the current selection.

The changes that delete content (non-empty A side).

The changes that insert content (non-empty B side).

DOM Range for a ProseMirror selection, for anchoring floating menus. A collapsed selection in an empty block or at the end of a textblock expands to the whole block so the range has non-zero size.

The editor id from the config plugin, or undefined outside a Stesura editor.

Attributes of the first mark of that type in the selection (stored marks first when collapsed), or {}.

Contiguous range of sibling nodes around $pos carrying a type mark with matching attributes (default: the attrs of the mark at $pos). Undefined when neither neighbour of $pos has the mark.

Marks between from and to with their ranges. Collapsed: the full extent of each mark active at from. Otherwise one entry per mark per node, ancestors included, unmerged.

Resolves a mark type from a name or MarkType instance, returning undefined if not found in the schema.

Attributes of the last node of that type touched by the selection (its ancestors included), or {}.

The attrs object of a node’s toDOM spec, or {} when it has none.

getNodeSpecAttrs filtered to data-*, for nodeviews that mirror toDOM but manage attrs like src/width/height in component state.

getNodeSpecAttrs as React props: class → className, style parsed to CSSProperties, HTML names camelCased (colspan → colSpan, for → htmlFor, …); the rest passes through.

React nodeviews should spread this, not the raw attrs: withGlobalAttributes always injects class/style into toDOM, and raw HTML names make React warn.

Resolves a node type from a name or NodeType instance, throwing if not found in the schema.

Finds the closest parent paragraph or heading node relative to the current selection.

For a sub-editor, the id of the editor that owns it; undefined for root editors.

The installed hook, or undefined (production / profiler not loaded).

Turns coordsAtPos-style edges into a DOMRect-shaped object, for anchoring floating UI.

Tries to get a node or mark type by its name.

Returns whether a schema item is a "node" or "mark", or null if it doesn’t exist.

Type guard that checks if a step is an AddMarkStep.

Type guard that checks if a step is an AddNodeMarkStep.

step as the AttrStep it amounts to in doc (the doc it applies to), for code reading block attr writes: a LifecycleStep’s, an AttrStep itself, else null.

A textblock’s lifecycle write (trackChanges), addressed by its ¶: the block’s content end, as Word keeps a paragraph’s revision on its mark. An AttrStep addresses the opening token, which a split leaves on the first half while the original ¶ goes to the last: mapped past a concurrent split (the server’s mapping, a rebase’s replay), it landed on the other client’s new half (TC-237). This step maps with the ¶, and fails (so is dropped) where no textblock ends: its ¶ was joined away.

Type guard that checks if a step is an AttrStep.

Checks if a transaction originates from history, or collaboration.

Whether a transaction is a collab-commit rebase: the client’s pending steps undone, a remote commit applied, the pending ones replayed (rebased counts them). The one client that sees both sides of a concurrent edit, so the one to repair what the merge broke (F4).

Whether a transaction applies collab changes.

collab$ is new PluginKey("collab").key: core’s vendored collab-commit (src/collab-commit), the only “collab” key loaded. Remote applies carry it, and so do collab-commit’s rebases, which replay the client’s own pending steps over the remote ones (their rebased meta counts them). Read as a string so prosemirror-collab’s transactions count too.

Type guard that checks if a step is a DocAttrStep.

Determines if a mark is active at the current selection (checks stored marks for empty selections).

Determines if a node type with optional matching attributes is active at the current selection.

Whether a transaction applies REMOTE collab changes. Same test as isCollabTransaction today; separate because read-only gating cares about remoteness, and a backend with local-origin collab meta would diverge here.

Type guard that checks if a step is a RemoveMarkStep.

Type guard that checks if a step is a RemoveNodeMarkStep.

Type guard that checks if a step is a ReplaceAroundStep.

Type guard that checks if a step is a ReplaceStep.

True when the doc is unchanged or the transaction is a single ReplaceStep that inserts only text and deletes only text within one textblock. Lets callers skip ChangeSet work for plain keystrokes.

Type guard that checks if a value is a ProseMirror TextSelection instance.

A run of text: its font and how many characters it holds.

True if node has any descendant other than an empty paragraph. Text nodes count too, so a whitespace-only paragraph is content.

Whether a node matching callback is an ancestor of a collapsed selection, or touched by a non-empty one.

Runs and returns fn, logging its duration when window.__pmBench is enabled.

Closes a pmBenchStart measurement and logs it, unindented. No-op when disabled.

Starts a measurement for a region that isn’t a clean callback; close it with pmBenchEnd.

Viewport bounding box of the coords at from and to (clamped to the doc), as a DOMRect-shaped object for positioning floating UI.

Load-time counterpart of a plugin’s appendTransaction: returns doc with the attrs and nodes the plugin would derive for it (ids, spacing, counters, …), or doc itself when it has nothing to add. state is the live editor’s, for its schema, config and stores; its doc is NOT the one being prepared.

Heals doc as createNormalizeTransaction would, then runs every plugin’s prepareDoc, in plugin order, until a round changes nothing. The heal comes first because the guard rewrites the load’s root transaction before any plugin sees it (clamped border widths feed spacing’s island borders). Plugin order is the order appendTransaction would derive in; the repeat covers derivations that read another’s output (cross-references read counters).

Mounting or dispatching the result instead of the raw doc turns a load into one transaction, or none: without it, the heal and the plugins emit one AttrStep per node per attr (CORE-156: ~25k steps for a 355-page import), and every consumer of those steps pays per step.

A dispatch that bypasses the read-only gate, for deliberate programmatic edits while mode is "view":

myCommand(view.state, privilegedDispatch(view));

Whether a profiler is installed. One property read — safe on hot paths.

One dispatch through useEditorCore’s dispatchTransaction. Emitted AFTER the pluginHook events it encloses, so a collector groups everything since the previous dispatch event under it.

One block of a pagination layout reconciliation. Layout px from the section top, at the block’s BOTTOM edge:

• expected: where the engine computed it to end (page top + header + offset);
• actual: where the DOM renders it ending;
• drift = actual − expected, cumulative; positive renders LOWER;
• step = drift − previous block’s drift. The FIRST non-zero step in document order is the root cause; later ones are usually cascade.

Drift at the first block of a page — the per-page view of the same series.

A settled pagination verify pass (overflow invariant) for one section, with the block-level DOM reconciliation so the overlay shows WHERE computed and rendered layout diverge. Emitted on every settled check while installed.

One React commit of the document subtree (a <React.Profiler> around ProseMirrorDoc), splitting reconciliation out of the dispatch window. Only fires in dev / profiling React builds.

Block content rendered outside the live editor so it lays out as the view would: paginated header and footer copies, a text box’s static render. Sanitized (painted from host toDOM specs too, SEC-77), ids stripped (the copy must not duplicate the live nodes’ ids, and the pagination margin rule keys on them), trailing breaks added. derived gives the derived values (counter labels, spacing) the live view renders (derivedResolverFor). Null without a DOM.

Table styles for a static render: the resolved sheet, and optionally the formats of a table rendered out of its context (the repeated header renders the header rows alone, but they resolve against the whole table).

Whether the selection runs exactly from the start to the end of the content of one styled block (its closest styled-block ancestor at both ends).

Puts the selection near the end of what the last step inserted. No-op unless steps were added after index startLen and the last is a replace step.

Replaces the node at getPos() with its content and dispatches. No-op for a missing or childless node.

Runs every v1 rule over a document; findings come back in document order.

The finding ids a checker (e.g. "accessibility") had dismissed on this document.

doc.attrs.dismissedFindings, cleaned: checker name to the finding ids dismissed under it.

Word border style name to its CSS border-style keyword.

A 1px solid black border with no padding.

All four outer sides set to createDefaultBorderOptions.

The first side (in a fixed order) whose style isn’t none, else createDefaultBorderOptions.

A table’s borders as the CSS custom properties its cells inherit (--table-border-outside-*, --table-border-inside-*). Cells fall back to these vars when they carry no border of their own.

The borders a border click would change, and the node type holding them:

• whole table selected: the table’s;
• inside a cell: the cell’s EFFECTIVE borders (getEffectiveCellBorders), since the cell writer wins over the block writer there;
• partial range inside one block: the border MARK, which is what the click would write;
• otherwise: the parent block’s.

The borders a cell actually displays: its own attr per side, else the table’s outside border on the table boundary and inside border elsewhere. cellPos is table-relative, as in TableMap.

The toggle logic and borders menu need this, not the raw attr: a cell in a default-bordered table has borders: null yet draws four lines.

Parses border-<side> declarations out of a CSS string into a Borders attr. Accepts hex and rgb/rgba colors (pasted spans carry rgb); sides that don’t match are left absent.

Every side of a Borders attr as CSS declarations, with an explicit border-<side>: none; for absent sides so nothing is inherited.

Every side of a Borders attr as a React style object.

Class names for a border-picker button, highlighting it when that side — or, for the all / outside composites, every side it covers — is active.

A border attr as the CSS shorthand VALUE it renders as (e.g. "1px solid #000000"), resolved like returnBorderStyles; an invisible border is the outline guide or "none".

Null when the attr is absent: the real cell border then cascades to a table-level var, which callers should fall back to as well. Used by the pagination cell view to copy a cell’s borders across page breaks.

One side of a Borders attr as a CSS declaration (e.g. "border-top: 1px solid #000000;").

A cell’s borders attr as CSS declarations for serialized HTML. Only the sides the cell sets are emitted: absent sides must keep cascading to the table-level --table-border-* vars, so no border-x: none filler. A side switched off carries its outline variable, so hosts showing the dashed guide get it on cells too.

The CSS a themed gradient paints on the canvas.

The theme’s canvas vars for one color scheme, already color-normalized.

Colour at fraction along the gradient, clamped to [0, 1] as CSS paints past the ends. Interpolates in sRGB like linear-gradient(from, to), so a gap’s slice matches the backdrop.

background for a gap rect inside a boxWidth × boxHeight gradient box that continues the backdrop seamlessly. All inputs share ONE space (visual px from the box’s top-left), unlike the clipped-copy approach this replaced; a stale rect costs a slightly-off shade, nothing more.

Emits an ANGLE, not the keyword: a corner keyword re-resolves against the box it’s painted on (on a wide flat gap, to bottom right runs nearly vertically). So the gap pins the backdrop’s resolved angle and samples colors at its own gradient-line endpoints (centre ± d·len/2, len = |w·sin α| + |h·cos α|). Both fields are linear along the same line, so every pixel matches.

Null when the colors can’t be parsed; callers fall back to the flat color.

The CSS angle (degrees, clockwise from “to top”) that direction resolves to on a boxWidth × boxHeight box. Cardinal keywords are fixed; corner keywords depend on the aspect ratio — the gradient line runs perpendicular to the diagonal joining the two other corners, i.e. along (±height, ±width).

Progress along the gradient (0 at from, 1 at to) for point (x, y) in a width × height box, origin top-left. Points outside the box extrapolate past [0, 1]; colorAtFraction clamps, as CSS does.

For a corner keyword, CSS runs the gradient line perpendicular to the line joining the two OTHER corners (css-images-3 §3.1.1), so those corners sit at exactly 50% for any aspect ratio: the MEAN of the per-axis fractions, not a projection onto the diagonal, which only agrees on square boxes (verified in Chrome: bottom-left of a 1400×900 to bottom right black→white box paints 128; the diagonal projection predicts 100).

Whether el renders in the dark color scheme: a .dark ancestor wins, else the OS preference unless the root has .light. Must mirror index.css’s —stesura-canvas-surface rules, so the gradient never disagrees with its flat fallback.

Parses rgb() / rgba() (what a computed style yields) or hex (read raw off an inline style). Anything else returns null, and the caller treats the gradient as unset; resolveColor in the DOM layer normalizes exotic formats through the browser first.

Resolves a theme’s canvas vars: a complete gradient wins, else the solid color, else nothing. Split from the DOM reader so the precedence is testable without a browser.

What a theme resolves to for the active color scheme.

The built-in kinds, in menu order, with the icon name the UI maps to an icon and the i18n key of their label (callout.kinds.<key>).

The callout the selection is in (the innermost, for nested ones), or the selected callout itself.

A callout and its position.

Coerces untrusted input (DOM, markdown, DOCX, collab JSON) to a kind: lowercased, [a-z][a-z0-9-]*, else the default.

Coerces untrusted input to a title: one trimmed line, capped, null when empty.

Alias of isInCodeBlock, kept for the editor-react text menu; prefer isInCodeBlock.

Whether either end of the selection is inside a code block.

Normalizes to a supported code language value; "" (with a warning) when unsupported.

Coerces a parsed value to a theme; anything but "light" is "dark".

Ties execute’s input type to the schema and derives run, which validates raw model input through the schema’s Standard Schema validate and then executes. run does not catch: the dispatcher that calls it does, and logs.

A function with overloads, not an arrow: one name for both tool kinds, each keeping its own execute signature, without a cast.

Returns a copy of comment with userId added to the emoji reaction group, creating the group if needed. Unchanged if the user already reacted.

Assumes a normalized blob — see normalizeSerializedThread.

Converts a persisted thread into a Thread. Never throws, whatever the input.

Drops malformed comments and reaction groups, keeping the persisted shape. Adapters must run it when reading a blob they are about to modify: the reaction helpers assume normalized input.

Returns a copy of comment without userId’s emoji reaction; emptied groups are dropped.

Assumes a normalized blob — see normalizeSerializedThread.

The comments-backend methods reviewing an agent’s comments needs: a structural subset of editor-react’s CommentAdapter.

Which pending changes to resolve. Every given field must match.

Pending changes matching filter among live threads.

Position of the first anchor of threadId: its opening boundary, or the node carrying it.

The agent’s pending changes on thread. Metadata is any member’s to write, and a JS adapter may leave it out, so anything malformed reads as no suggestion.

Accepts (approve: the changes stay, the markers go) or rejects (reject: a created thread is deleted and its anchors removed in one undoable step, a reply deleted, a resolve reopened) the agent’s pending comment changes in threads that match filter. One thread failing doesn’t stop the others. Resolves to how many changes were resolved and how many failed.

Selects the start of threadId’s anchor and scrolls to it. False when the thread has no anchor.

The mount’s allowedFileHosts (a ConfigPluginConfig field), or undefined when unset, which means no PDF previews at all (every PDF is a card).

The toast emitter for this mount. Emitters pass a ToastMessage key; the host’s onToast gets it with description localized (resolver installed by editor-react; a bare-core mount falls back to the key).

Without onToast the mount is warned ONCE, since the refusals that raise toasts can fire on every keystroke.

Whether this mount renders for the PDF export rather than the screen, so screen-only chrome (handles, hover affordances, floating menus) can stay out of the capture.

Reads the printMount config (see ConfigPluginConfig), known from the first render. Pass the state when there is one: without it, or for states built without the flag (e.g. a sub-editor’s), it falls back to the data-stesura-print stamp ExportController puts on the root, which only exists once the export page has mounted.

Coerces a parsed value to a CrossRefType; unknown values become "default".

Every numbered block’s clause label by block id, derived from its number: { own: "(a)", tokens: ["5", "2", "a"], label: "5.2(a)" }. Bullets, empty levels and blocks pending deletion have none. Computed from the numbering store and memoized per document.

A paragraph number as a cross-reference shows it: without trailing full stops, as Word’s REF field shows it under its paragraph-number switches (“17.3.” reads “17.3”). Other punctuation stays: “(a)”, “1)”.

A reference’s numbering tokens, outermost first and folded, and its other words: “paragraph (b) of clause 5.2” → tokens 5, 2, b. Compare the tokens with a ClauseLabel’s tokens (the full path) or with tokenizeReference(label) (as cited).

Accents folded, lower case: how references and labels are compared.

Shrinks ProseMirror JSON by dropping every node/mark attr equal to its schema default. No DOM or EditorState, so it is safe on the server; live-doc callers pass doc.toJSON(). Use it before persisting or sending a doc: a style-heavy import writes ~12 mostly-default attrs on every textStyle mark.

Lossless: fromJSON fills absent keys with the spec default, so the result parses to a doc .eq() to the original. Attrs without a declared default, and attrs the schema does not declare, are kept.

One observable difference from expanded JSON: a compacted doc adopts future changes to a spec default instead of freezing today’s value.

Returns the input object when nothing was dropped.

Builds a document from simple blocks without touching the DOM, so it is safe in server code — where HTML initialContent cannot be parsed (see createInitialDoc). For rich templates, seed from a published snapshot’s JSON instead of building blocks by hand.

The editor’s starting doc: initialContent converted to the schema, or a single empty section when absent. Throws on HTML content outside the browser.

A text run; marks are schema mark names (e.g. "strong", "em") with default attrs.

Fills missing node ids and regenerates duplicates in ProseMirror JSON. No DOM or EditorState, so it is safe on the server.

Run it before persisting seeded docs (e.g. createRoomDoc initialContent) so clients never mount an id-less doc and race each other to heal it.

Duplicate section ids are regenerated like any other, after the first occurrence: nothing is cached yet, and two sections sharing an id share every pagination store keyed by it. Each one is reported through onDuplicateSectionId, since only a bug upstream produces one.

Returns the input object when nothing changed.

Indentation attrs as CSS declarations, for the stylesheet’s generated rules (the non-numbered geometry — formattingIndentDeclarations).

The document’s default direction, never null: the bottom of the direction chain, and what a host sets for an RTL-by-default editor.

The direction the block at $pos INHERITS (its own dir ignored): the nearest ancestor declaring one, else the document default. Walks ancestors rather than finding the section so it works in sub-editors, whose wrapper (a section clone) is seeded with the owning section’s direction.

The formatted node at the selection together with its resolved style definition.

getNodeFormattingFromSelection for a node you already hold.

The effective indent, spacing, lineHeight and textAlign of the formatted node at the cursor: node attr, then (indent only) the numbering- derived tier, then the style; lineHeight finally falls back to the default.

The effective text direction of a block: its own dir, else what it inherits at the selection (see getInheritedDirection).

A section’s effective direction: its own dir, else the document default. Takes attrs rather than a node so a sub-editor’s wrapper attrs qualify too.

Allowlist guard: dir is raw on the JSON/collab path, like textAlign.

Parses a line height to a multiplier, clamped to its range but not snapped to LINE_HEIGHTS (Word values like 1.08 survive a copy/paste). Null for an absent value (“inherit from the stylesheet”), the app default for an uninterpretable one.

An “Xpt” height passes through untouched: it is the attr’s other legal shape (DOCX exact/atLeast spacing), and snapping it would lose the fixed line box on every DOM round-trip.

Coerces a parsed value to IndentationSpecials; unknown values become "none".

Indentation attrs as an inline CSS string (leading ;, for appending).

Numbering changes the result: the counter occupies the first-line indent, and followBy (tab, space or nothing) decides how the text after it lines up. --tabStop is emitted only when set, so it overrides the level config and the editor default through the CSS var cascade.

Spacing attrs as the --spacing-before / --spacing-after CSS declarations.

spacingAttrsToCss as a React style object.

The style and data-* attributes a spaced node’s toDOM emits: the collapsed margins and paddings the spacing store computes (derived, by default the render context’s), plus the raw spacing values so a serialized document round-trips.

Which non-default variants exist as header_footer_content nodes in the section’s header or footer (true if either has it).

The header_footer_content node of variant at section > section_header|section_footer in fragment, e.g. a full-doc replace step’s slice. Sections must be top-level children of fragment.

The header_footer_content node (and its position) for a section, target and variant in the main doc. Its position is the sub-editor’s step-mapping offset.

Content of the header_footer_content node for a section, target and variant.

The highlighter plugin’s state — notably the armed color, if any.

Check if a background-color value is a highlight color

math_inline or math_display.

The storable form of a mark set, minus null and default-valued attrs (create fills them back in). Scalar comparison is enough: the only non-scalar attr (off) defaults to null.

An equation’s styling, hydrated from its mathMarks attr.

The CSS (colour, size, background) an equation’s stored marks resolve to. For the React nodeview, which owns the math DOM and so bypasses toDOM.

The selected node, when the selection is exactly one math node.

The angle a page is drawn at: the file node’s rotation ADDED to the page’s own. react-pdf’s Page.rotate and pdf-lib’s setRotation REPLACE the native angle, so preview and export both add it back through this one formula.

The name shown for a file: the uploaded filename, else the URL’s last segment.

The behaviour class of a file node. pdf is the only kind with page semantics (previewable; under pagination it sits on the canvas between two pages; spliced into the PDF export). A null mimeType means the node predates the attr, and only PDFs could be uploaded then.

Whether a PDF file node is PREVIEWED on this mount: the one decision the node view, the pagination engine and the PDF export must agree on. All three read the same store entry, so a mount without the viewer package is a card everywhere.

Five conditions, all required:

• the node is a PDF (fileKind);
• the author left displayPreview on;
• @stesura/pdf-viewer-react is mounted (ready);
• the mount CONFIGURED allowedFileHosts — the renderer fetches the file from the viewer’s browser, so the integrator has to have named the hosts they trust to serve nothing but PDFs (SEC-70);
• the src passes that allowlist and the never-allow class.

Coerce anything (a parsed data-rotation, an API caller’s number) to one of the four storable angles. Out-of-range multiples of 90 wrap; everything else falls back to 0 rather than storing an angle the export cannot reproduce.

New objects sit at the right edge of their column, from the top of their paragraph.

Word’s default gap for a wrap mode, px: ⅛” either side of a float, none above and below.

The gap actually used: the stored one, else the mode’s default.

The gaps a wrap mode lets the user set, as Word’s Layout dialog enables them: all four for square, left and right for tight (its top and bottom follow the contour), top and bottom for top and bottom, none where no text wraps (inline, front, behind).

The position that puts a float on side, keeping the vertical axis.

The DOM role pagination and the column layout key on (data-float): a float band, an out-of-flow layer, or an inline box.

Which side a float sits on: its horizontal alignment, else the column half its middle falls in (columnWidth and width known), else right.

A child that floats beside the text, so its textblock must contain it.

Floated beside the text: the object and the lines next to it paginate as one band.

Carries the floating family.

Out of flow, in front of or behind the text.

Structural equality, so normalizers can hand back the same object when nothing changed.

Wrap distances from untrusted data, or null when absent or malformed.

A position from untrusted data; invalid parts fall back to the default’s.

A wrap value from untrusted data; unknown values become “inline”.

A stacking order from untrusted data, or null.

A box’s outline; width in px.

Word’s default text box insets: 0.1” left and right, 0.05” top and bottom.

The box’s layout as inline CSS: size, padding, border width and style. The shadow measurer clones DOM, so these cannot live in a stylesheet. Colors go through custom properties that floating-box.css reads.

Every own attr through its coercer: the shape parseDOM and the commands hand the node.

An outline from untrusted data: the default when absent, null for none. An unusable color falls back to the default’s.

A fixed height, or null (grows with the content) when absent or malformed.

One trimmed line, capped; null when empty.

Padding from untrusted data; Word’s insets when absent or malformed.

Turns a data URI into a File, for handing pasted image data to the uploader. Handles both base64 and URL-encoded (RFC 2397) payloads; returns null for malformed input instead of throwing (CORE-97).

Coerces a parsed value to an ImageWrap; anything but "square" is "top-bottom".

Reads the three-state alt back off an <img>. Uses the raw attribute: img.alt returns "" for a MISSING one, turning undeclared into decorative.

The alt attribute for the three-state alt model:

• decorative → alt="" (assistive tech skips it)
• meaningful → the text
• undeclared → null, i.e. no attribute, so automated checks flag it instead of reading it as decorative.

toDOM skips null attrs; React call sites map it to undefined.

Where the full bitmap sits inside a cropped picture’s box: its size and its (negative) offset, so a clipping box of width×height shows exactly the uncropped part. Null when nothing is cropped.

A picture’s rotation and mirroring as a CSS transform — mirroring first, as in Word.

The box a width×height picture turned by rotation degrees occupies, from its uppermost corner to its lowermost and leftmost to rightmost. What the page reserves for it: pagination measures it, and DOCX’s wp:effectExtent is the overhang past the unturned size.

A safe image src, or null. RASTER data: URIs pass (the default upload strategy stores them); everything else goes through safeNormalizeUrl, so javascript: and friends never reach the doc or get loaded for measurement. The scheme is kept: upload storage may be plain http.

data:image/svg+xml is excluded, as in the markdown parser (SEC-2) and the upload sniffer (SEC-9): SVG can carry scripts, inert in <img>, but a stored attr must not depend on where it is later rendered.

Installs the app’s image uploader (pass null to uninstall). Without one, images are stored inline as data URIs — fine for local-only documents, not for docs that sync or persist (see imageUploadPolicy for the guard).

Inserts a placeholder at pos (or replacing the selection), uploads the file or loads the URL, then swaps in an image node sized to fit the section. The placeholder is removed on failure; srcs are sanitized before reaching the doc. A file is refused up front when the mount disallows inline images and no upload strategy is installed.

Coerces a parsed value (left/right accepted) to an ImageAlign; unknown values become "center".

A crop from untrusted data (a pasted data-crop, a collab step), or null: each edge a percent, and something left visible on both axes.

A transform from untrusted data, or null when it turns nothing.

An image file’s src, stored as image insertion stores it (the upload strategy, else inline), for srcs that aren’t an image node’s: a picture watermark. Null when the file isn’t an image the policy accepts, the mount refuses inline images without a strategy, or the resulting src isn’t safe.

Lets host schema extensions keep non-standard tags/attributes on the sanitized surfaces. Additive only: the forbidden tags, event handlers and srcdoc/formaction cannot be registered, and invalid names are ignored.

Each tab’s width, Word’s way: a tab advances to the first stop past where it starts (custom stops, then the default interval past the last one), and the text after it aligns against that stop. A hanging indent’s text position is an implicit stop, which lines up “1.1⇥Text”.

A stop past lineEnd (the text area’s end edge) acts as if it were on it, so the tab never wraps. A wrapped tab was measured on the next line, which changed its width, which unwrapped it: a measure loop that never settled.

The implicit stop a hanging indent sets: its text position, px from the start edge.

One tab of a line, as measured: the text after it up to the next tab.

A tabStops value from untrusted data (pasted HTML, a stored document) as valid stops sorted by position; invalid entries are dropped. An empty input stays [] (“no stops”, overriding the style’s); null means inherit.

A block’s tab stops: its own, else its paragraph style’s. Whole-list override, like Word’s resolved set.

A laid-out tab: its width and the leader that fills it.

Whether the pilcrow / space / tab markers are currently shown.

The document default, guaranteed to be a value rather than null.

The effective proofing language of the current selection, or undefined when the selection spans several. See getSelectionLanguage for the explicit-vs-inherited flag.

The EFFECTIVE proofing language of the selection’s proofread blocks, plus whether it is explicit or inherited. Resolved per block before the mixed check, so an inherited-French and an explicit-French paragraph read as French.

The language a paragraph style supplies (the middle level of the chain), or null when it states none. Unknown ids fall back to Normal, as in the CSS: a block with a dangling style renders, and so proofs, as Normal.

Pass the RESOLVED sheet (getResolvedStyleSheet or getResolvedStyleSheetFromDoc) so basedOn is already applied.

The effective language of one proofread block: proofingLanguage ?? style.language ?? doc.language. Walking consumers resolve the sheet once and call this per block.

The effective language at pos, resolved via the nearest proofread ancestor (or the block right after pos); the doc language when there is none.

What the selection’s proofread blocks resolve to, and whether they say so.