edentext/docs/architecture/frames.md

Frames: images and text boxes

Covers src/lib/editor/extensions/image.ts and textBox.ts — node views, resize/rotate handles, wrap modes, frame offsets — and their ODF/DOCX legs.

• image.ts (Image) — inline, as-character image atom (Word's "in line with text"). Attrs: src (data-URI), alt, width/height (unscaled doc px @96dpi, like rowHeight), rotation (CW degrees). The node view nests an <img> in a rotated "rotor" inside an axis-aligned wrapper that reserves the rotated bounding box (so text reflows around it). The rotor's transform makes it a stacking context, so a selected .image-node is given a z-index above the header/footer layer to keep handles that poke into a margin grabbable. It has eight zoom-aware resize handles — corners aspect-locked, edges single-axis (width- or height-only) — plus a rotation-arrow grip, and shows a live "Width … × Height …" (cm) badge while resizing; resize deltas are un-rotated onto the image's own axes so handles track the pointer at any angle (drag math mirrors tableRowResize.ts; width cap = the cell or page-text-column, height cap = the page text height). setImage command inserts it; the toolbar button (ToolbarExpanded), drag-drop and paste (Editor.svelte) read the file via FileReader → data-URI and clamp the initial size to the page text box. Text wrap: the wrap attr ('inline'|'left'|'right'|'topBottom') makes the image a floating frame — ImageToolbar.svelte (a per-image floating toolbar wired in Editor.svelte like TableToolbar) sets the mode; left/right float the wrapper at its anchor paragraph (text flows on the open side via CSS float), topBottom is a full-width float (text only above/below). All modes use float deliberately: an in-flow display:block on an inline-atom node view splits the paragraph's inline content into anonymous block boxes, which desyncs ProseMirror's inline view descriptor and makes it drop the following page-break spacer widget; a float is out-of-flow and avoids that. Dragging an inline image runs ProseMirror's native node move (the dropCursor plugin shows the caret). Dragging a floating image runs a custom drag (ImageView.startReposition) that live re-anchors the node to the text position under the cursor, so the float and text reflow in real time as you drag; it's rAF-throttled and only moves when the cursor's line changes (a float can't move within a line), and stays a single undo step (first move records history, later moves are addToHistory:false and get rebased on undo). A paragraph that contains an image paginates atomically (pageBreaks.ts — pushed whole to the next page, spacer placed before it) so a page break never splits the paragraph next to the image's float (where ProseMirror drops the spacer widget). Frame offsets: wrapOffset is the frame's left edge in the text column (Word's positionH posOffset, ODF svg:x), rendered as the float's near/far margin against the live column vars — an indented anchor paragraph can't skew it — and shared with textBox.ts through frameMargins. A topBottom float spans the column, so its own x moves the rotor inside the wrapper instead. wrapOffsetY (positionV, svg:y) is the frame's top below the anchor paragraph's, drawn for topBottom only — no text sits beside such a frame, where a side float's top margin would push away lines Word keeps. Chromium places every line after a full-width float below it, even the ones the float's top margin leaves room for, so a frame set below the paragraph top is sunk behind that paragraph's text at import (sinkOffsetFrames, both importers) and ImageView.sinkToOffset measures what the lines above it already cover, adding only the rest. Two topBottom frames set against opposite ends of nearby paragraphs (wrapAlign, from Word's positionH align / ODF style:horizontal-pos) share one band and float to their own sides instead: pairAlignedFrames (import/odt.ts, both importers) keeps the attr only for such a pair — a lone one reserves the whole band, which is what the wrap means — and scales a pair up to 15% wider than the column down to it, since Word lets the two overlap in the middle and two floats cannot. A frame Word puts inside running text still lands after it: browsers can't wrap text around a freely-positioned box (CSS Exclusions are unimplemented). Inline images stay as-char. Works inside table cells. Not available while editing a header/footer (the HF schema has no image node). Images live as data-URIs in the autosaved JSON; autosave.ts warns once if that exceeds the localStorage quota.
• textBox.ts (TextBox) — block-level text box / basic shape with editable block content (content: '(paragraph|heading|bulletList|orderedList)+', isolating). Attrs: width/height (px @96dpi; height renders as min-height — content grows the box), rotation (CW deg), wrap (image's WrapMode; inline renders in-flow, floats via CSS float like ImageView.applyWrap), shapeKind ('textbox'|'roundRect'|'ellipse' — ellipse renders via border-radius:50%), fillColor/strokeColor (null = transparent/no border), strokeWidthPt. Padding is the fixed TEXTBOX_PADDING_CM (0.15cm). The node has its own group (group: 'textBox') so only the document admits it (extensions.ts widens Document to '(block | textBox)+') — never in table cells, lists, header/footer, or other boxes; imports found there are flattened with a warning. TextBoxView mirrors ImageView (wrapper reserving the rotated bbox → rotor carrying fill/stroke/rotation → contentDOM); the rotor is out of flow and auto-grows, so a ResizeObserver refits the wrapper. Click model (Word-like): stopEvent/isFrameHit claim mouse events on a ~6px frame ring (rotation-/zoom-aware) → NodeSelection + handles (the shared image-* handle classes/CSS); clicks further inside pass to ProseMirror (caret). The box is browser-draggable only while node-selected, so PM's native block drag moves it without hijacking text selection. Commands: insertTextBox() (after the current top-level block, cursor inside), setTextBoxAttrs() (NodeSelection or cursor inside; helper findTextBox). TextBoxToolbar.svelte (wired in Editor.svelte like the image toolbar, also shown while the caret is inside a box) sets wrap/shape/fill/stroke. trailingNode.ts appends a paragraph after a trailing box; pageBreaks.ts paginates .textbox-node atomically. Spacing: a box lifted out of an anchor paragraph that held nothing else stands in for it, so it takes that paragraph's resolved fo:margin-top/-bottom as spaceBefore/spaceAfter (ParagraphSpacing covers textBox for that). Space above is padding — it adds to the block above rather than collapsing against it — which means the node is content-box and the rotor, centred in the padding box, gets half of it back.