@stll/folio-core 0.1.3 → 0.2.0

package/dist/layout-painter/sdtBoundary.d.ts

@@ -1,6 +1,29 @@
 import { SdtGroup } from "../layout-engine/types.js";
+import { Node } from "prosemirror-model";
 
 //#region src/layout-painter/sdtBoundary.d.ts
 declare function applySdtDataAttrs(el: HTMLElement, sdtGroups: readonly SdtGroup[] | undefined): void;
+/**
+ * Identities of every block-level content control (`w:sdt`) that encloses the
+ * given selection — used to keep a control's boundary visible while the caret
+ * is inside it (Word-style focus), independent of mouse hover. Both ends of a
+ * range are collected so a selection straddling a control still lights it up.
+ *
+ * Ported from eigenpal/docx-editor `layout-painter/sdtBoundary.ts`. Upstream
+ * keyed the set on `sdt@${pos}` to match per-control boundary boxes; this fork
+ * stamps the SDT node's PM position as `data-sdt-pm-pos` on the painted block
+ * elements (see `applySdtDataAttrs`), so the identity here is the stringified
+ * `$pos.before(d)` — which is exactly that PM position — keeping the returned
+ * ids in lockstep with what `applySdtFocus` hit-tests against.
+ */
+declare function enclosingSdtGroupIds(doc: Node, from: number, to: number): Set<string>;
+/**
+ * Toggle the `.is-focused` reveal class on every painted block whose enclosing
+ * content control encloses the caret. Kept separate from any hover-driven
+ * reveal so the two paths never clear each other. Matches the fork's
+ * `data-sdt-pm-pos` stamping (upstream matched `.layout-block-sdt-box`'s
+ * `data-sdt-group-id`, which this fork does not paint).
+ */
+declare function applySdtFocus(container: HTMLElement, focusedIds: Set<string>): void;
 //#endregion
-export { applySdtDataAttrs };
+export { applySdtDataAttrs, applySdtFocus, enclosingSdtGroupIds };

package/dist/layout-painter/sdtBoundary.js

@@ -24,5 +24,44 @@ function applySdtDataAttrs(el, sdtGroups) {
 		alias: g.alias ?? null
 	})));
 }
+/**
+* Identities of every block-level content control (`w:sdt`) that encloses the
+* given selection — used to keep a control's boundary visible while the caret
+* is inside it (Word-style focus), independent of mouse hover. Both ends of a
+* range are collected so a selection straddling a control still lights it up.
+*
+* Ported from eigenpal/docx-editor `layout-painter/sdtBoundary.ts`. Upstream
+* keyed the set on `sdt@${pos}` to match per-control boundary boxes; this fork
+* stamps the SDT node's PM position as `data-sdt-pm-pos` on the painted block
+* elements (see `applySdtDataAttrs`), so the identity here is the stringified
+* `$pos.before(d)` — which is exactly that PM position — keeping the returned
+* ids in lockstep with what `applySdtFocus` hit-tests against.
+*/
+function enclosingSdtGroupIds(doc, from, to) {
+	const ids = /* @__PURE__ */ new Set();
+	const max = doc.content.size;
+	const collect = (pos) => {
+		const $pos = doc.resolve(Math.max(0, Math.min(pos, max)));
+		for (let d = 1; d <= $pos.depth; d++) if ($pos.node(d).type.name === "blockSdt") ids.add(String($pos.before(d)));
+	};
+	collect(from);
+	if (to !== from) collect(to);
+	return ids;
+}
+/**
+* Toggle the `.is-focused` reveal class on every painted block whose enclosing
+* content control encloses the caret. Kept separate from any hover-driven
+* reveal so the two paths never clear each other. Matches the fork's
+* `data-sdt-pm-pos` stamping (upstream matched `.layout-block-sdt-box`'s
+* `data-sdt-group-id`, which this fork does not paint).
+*/
+function applySdtFocus(container, focusedIds) {
+	const boxes = container.querySelectorAll("[data-sdt-boundary]");
+	for (const box of boxes) {
+		const id = box.dataset["sdtPmPos"];
+		const on = id != null && focusedIds.has(id);
+		if (on !== box.classList.contains("is-focused")) box.classList.toggle("is-focused", on);
+	}
+}
 //#endregion
-export { applySdtDataAttrs };
+export { applySdtDataAttrs, applySdtFocus, enclosingSdtGroupIds };

package/dist/managers/AutoSaveManager.d.ts

@@ -0,0 +1,89 @@
+import { document_d_exports } from "../types/document.js";
+import { Subscribable } from "./Subscribable.js";
+
+//#region src/managers/AutoSaveManager.d.ts
+/** Auto-save status. */
+type AutoSaveStatus = "idle" | "saving" | "saved" | "error";
+/** Configuration for {@link AutoSaveManager}. */
+type AutoSaveManagerOptions = {
+  /** Storage key for localStorage (default: 'docx-editor-autosave'). */storageKey?: string; /** Save interval in milliseconds (default: 30000 - 30 seconds). */
+  interval?: number; /** Maximum age of auto-save before it is considered stale (default: 24 hours). */
+  maxAge?: number; /** Whether to save on document change with debounce (default: true). */
+  saveOnChange?: boolean; /** Debounce delay for saveOnChange in milliseconds (default: 2000). */
+  debounceDelay?: number; /** Callback when save succeeds. */
+  onSave?: (timestamp: Date) => void; /** Callback when save fails. */
+  onError?: (error: Error) => void; /** Callback when recovery data is found. */
+  onRecoveryAvailable?: (savedDocument: SavedDocumentData) => void;
+};
+/** Saved document data structure. */
+type SavedDocumentData = {
+  /** The document. */document: document_d_exports.Document; /** When the document was saved (ISO string). */
+  savedAt: string; /** Version for format compatibility. */
+  version: number; /** Optional document identifier. */
+  documentId?: string;
+};
+/** AutoSaveManager snapshot for UI consumption. */
+type AutoSaveSnapshot = {
+  status: AutoSaveStatus;
+  lastSaveTime: Date | null;
+  hasRecoveryData: boolean;
+  isEnabled: boolean;
+};
+declare class AutoSaveManager extends Subscribable<AutoSaveSnapshot> {
+  private readonly storageKey;
+  private readonly interval;
+  private readonly maxAge;
+  private readonly saveOnChange;
+  private readonly debounceDelay;
+  private readonly onSaveCallback;
+  private readonly onErrorCallback;
+  private readonly onRecoveryAvailableCallback;
+  private readonly storageAvailable;
+  private currentDocument;
+  private lastSavedJson;
+  private intervalTimer;
+  private debounceTimer;
+  private status;
+  private lastSaveTime;
+  private hasRecoveryData;
+  private isEnabled;
+  constructor(options?: AutoSaveManagerOptions);
+  /** Update the current document. Triggers a debounced save if enabled. */
+  onDocumentChanged(document: document_d_exports.Document | null): void;
+  /** Manually trigger a save. */
+  save(): boolean;
+  /** Clear auto-saved data from storage. */
+  clear(): void;
+  /** Get recovery data from storage. */
+  getRecoveryData(): SavedDocumentData | null;
+  /** Accept recovery and return the document. */
+  acceptRecovery(): document_d_exports.Document | null;
+  /** Dismiss recovery and clear saved data. */
+  dismissRecovery(): void;
+  /** Enable auto-save and start the interval timer. */
+  enable(): void;
+  /** Disable auto-save and stop all timers. */
+  disable(): void;
+  /** Start the interval timer. Call after enabling or on init. */
+  startInterval(): void;
+  /** Save synchronously on destroy (best-effort). */
+  destroy(): void;
+  private checkRecoveryData;
+  private persistToStorage;
+  private debounceSave;
+  private stopTimers;
+  private updateStatus;
+  private emitSnapshot;
+}
+/** Format last save time for display. */
+declare function formatLastSaveTime(date: Date | null): string;
+/** Get auto-save status label. */
+declare function getAutoSaveStatusLabel(status: AutoSaveStatus): string;
+/** Get storage size used by auto-save (bytes). */
+declare function getAutoSaveStorageSize(storageKey?: string): number;
+/** Format storage size for display. */
+declare function formatStorageSize(bytes: number): string;
+/** Check whether auto-save is supported. */
+declare function isAutoSaveSupported(): boolean;
+//#endregion
+export { AutoSaveManager, AutoSaveManagerOptions, AutoSaveSnapshot, AutoSaveStatus, SavedDocumentData, formatLastSaveTime, formatStorageSize, getAutoSaveStatusLabel, getAutoSaveStorageSize, isAutoSaveSupported };

package/dist/managers/AutoSaveManager.js

@@ -0,0 +1,279 @@
+import { Subscribable } from "./Subscribable.js";
+//#region src/managers/AutoSaveManager.ts
+const DEFAULT_STORAGE_KEY = "docx-editor-autosave";
+const DEFAULT_INTERVAL = 3e4;
+const DEFAULT_MAX_AGE = 1440 * 60 * 1e3;
+const DEFAULT_DEBOUNCE_DELAY = 2e3;
+const SAVE_VERSION = 1;
+function isLocalStorageAvailable() {
+	try {
+		const testKey = "__docx_editor_test__";
+		localStorage.setItem(testKey, "test");
+		localStorage.removeItem(testKey);
+		return true;
+	} catch {
+		return false;
+	}
+}
+function serializeForStorage(document) {
+	return JSON.stringify({
+		...document,
+		originalBuffer: null
+	});
+}
+function isDocumentLike(value) {
+	return typeof value === "object" && value !== null && "package" in value;
+}
+function parseSavedData(json) {
+	let parsed;
+	try {
+		parsed = JSON.parse(json);
+	} catch {
+		return null;
+	}
+	if (typeof parsed !== "object" || parsed === null) return null;
+	if (!("document" in parsed) || !("savedAt" in parsed) || !("version" in parsed)) return null;
+	const { document, savedAt, version } = parsed;
+	if (typeof savedAt !== "string" || typeof version !== "number") return null;
+	if (!isDocumentLike(document)) return null;
+	return {
+		document,
+		savedAt,
+		version
+	};
+}
+function isStale(savedAt, maxAge) {
+	const savedTime = new Date(savedAt).getTime();
+	return Date.now() - savedTime > maxAge;
+}
+var AutoSaveManager = class extends Subscribable {
+	storageKey;
+	interval;
+	maxAge;
+	saveOnChange;
+	debounceDelay;
+	onSaveCallback;
+	onErrorCallback;
+	onRecoveryAvailableCallback;
+	storageAvailable;
+	currentDocument = null;
+	lastSavedJson = null;
+	intervalTimer = null;
+	debounceTimer = null;
+	status = "idle";
+	lastSaveTime = null;
+	hasRecoveryData = false;
+	isEnabled;
+	constructor(options = {}) {
+		super({
+			status: "idle",
+			lastSaveTime: null,
+			hasRecoveryData: false,
+			isEnabled: true
+		});
+		this.storageKey = options.storageKey ?? DEFAULT_STORAGE_KEY;
+		this.interval = options.interval ?? DEFAULT_INTERVAL;
+		this.maxAge = options.maxAge ?? DEFAULT_MAX_AGE;
+		this.saveOnChange = options.saveOnChange ?? true;
+		this.debounceDelay = options.debounceDelay ?? DEFAULT_DEBOUNCE_DELAY;
+		this.onSaveCallback = options.onSave;
+		this.onErrorCallback = options.onError;
+		this.onRecoveryAvailableCallback = options.onRecoveryAvailable;
+		this.isEnabled = true;
+		this.storageAvailable = isLocalStorageAvailable();
+		this.checkRecoveryData();
+	}
+	/** Update the current document. Triggers a debounced save if enabled. */
+	onDocumentChanged(document) {
+		this.currentDocument = document;
+		if (this.isEnabled && this.saveOnChange && document && this.storageAvailable) this.debounceSave();
+	}
+	/** Manually trigger a save. */
+	save() {
+		if (!this.storageAvailable) {
+			this.onErrorCallback?.(/* @__PURE__ */ new Error("localStorage is not available"));
+			return false;
+		}
+		const doc = this.currentDocument;
+		if (!doc) return false;
+		this.updateStatus("saving");
+		try {
+			const serialized = serializeForStorage(doc);
+			if (serialized === this.lastSavedJson) {
+				this.updateStatus("saved");
+				return true;
+			}
+			this.persistToStorage(doc);
+			this.lastSavedJson = serialized;
+			const saveTime = /* @__PURE__ */ new Date();
+			this.lastSaveTime = saveTime;
+			this.updateStatus("saved");
+			this.onSaveCallback?.(saveTime);
+			return true;
+		} catch (error) {
+			this.updateStatus("error");
+			this.onErrorCallback?.(error instanceof Error ? error : new Error(String(error)));
+			return false;
+		}
+	}
+	/** Clear auto-saved data from storage. */
+	clear() {
+		if (!this.storageAvailable) return;
+		try {
+			localStorage.removeItem(this.storageKey);
+			this.hasRecoveryData = false;
+			this.lastSavedJson = null;
+			this.emitSnapshot();
+		} catch (error) {
+			this.onErrorCallback?.(error instanceof Error ? error : new Error(String(error)));
+		}
+	}
+	/** Get recovery data from storage. */
+	getRecoveryData() {
+		if (!this.storageAvailable) return null;
+		const savedJson = localStorage.getItem(this.storageKey);
+		if (!savedJson) return null;
+		const savedData = parseSavedData(savedJson);
+		if (!savedData) return null;
+		if (isStale(savedData.savedAt, this.maxAge)) {
+			this.clear();
+			return null;
+		}
+		return savedData;
+	}
+	/** Accept recovery and return the document. */
+	acceptRecovery() {
+		const data = this.getRecoveryData();
+		if (!data) return null;
+		this.hasRecoveryData = false;
+		this.emitSnapshot();
+		return data.document;
+	}
+	/** Dismiss recovery and clear saved data. */
+	dismissRecovery() {
+		this.clear();
+		this.hasRecoveryData = false;
+		this.emitSnapshot();
+	}
+	/** Enable auto-save and start the interval timer. */
+	enable() {
+		this.isEnabled = true;
+		this.startInterval();
+		this.emitSnapshot();
+	}
+	/** Disable auto-save and stop all timers. */
+	disable() {
+		this.isEnabled = false;
+		this.stopTimers();
+		this.emitSnapshot();
+	}
+	/** Start the interval timer. Call after enabling or on init. */
+	startInterval() {
+		this.stopTimers();
+		if (!this.isEnabled || !this.storageAvailable) return;
+		this.intervalTimer = setInterval(() => {
+			this.save();
+		}, this.interval);
+	}
+	/** Save synchronously on destroy (best-effort). */
+	destroy() {
+		this.stopTimers();
+		if (this.isEnabled && this.currentDocument && this.storageAvailable) try {
+			this.persistToStorage(this.currentDocument);
+		} catch (error) {
+			this.onErrorCallback?.(error instanceof Error ? error : new Error(String(error)));
+		}
+	}
+	checkRecoveryData() {
+		if (!this.storageAvailable) return;
+		const data = this.getRecoveryData();
+		if (data) {
+			this.hasRecoveryData = true;
+			this.emitSnapshot();
+			this.onRecoveryAvailableCallback?.(data);
+		}
+	}
+	persistToStorage(document) {
+		const dataToSave = {
+			document: {
+				...document,
+				originalBuffer: null
+			},
+			savedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			version: SAVE_VERSION
+		};
+		localStorage.setItem(this.storageKey, JSON.stringify(dataToSave));
+	}
+	debounceSave() {
+		if (this.debounceTimer) clearTimeout(this.debounceTimer);
+		this.debounceTimer = setTimeout(() => {
+			this.save();
+		}, this.debounceDelay);
+	}
+	stopTimers() {
+		if (this.intervalTimer) {
+			clearInterval(this.intervalTimer);
+			this.intervalTimer = null;
+		}
+		if (this.debounceTimer) {
+			clearTimeout(this.debounceTimer);
+			this.debounceTimer = null;
+		}
+	}
+	updateStatus(status) {
+		this.status = status;
+		this.emitSnapshot();
+	}
+	emitSnapshot() {
+		this.setSnapshot({
+			status: this.status,
+			lastSaveTime: this.lastSaveTime,
+			hasRecoveryData: this.hasRecoveryData,
+			isEnabled: this.isEnabled
+		});
+	}
+};
+/** Format last save time for display. */
+function formatLastSaveTime(date) {
+	if (!date) return "Never";
+	const diffMs = (/* @__PURE__ */ new Date()).getTime() - date.getTime();
+	const diffSec = Math.floor(diffMs / 1e3);
+	const diffMin = Math.floor(diffSec / 60);
+	const diffHour = Math.floor(diffMin / 60);
+	if (diffSec < 10) return "Just now";
+	if (diffSec < 60) return `${diffSec} seconds ago`;
+	if (diffMin < 60) return `${diffMin} minute${diffMin === 1 ? "" : "s"} ago`;
+	if (diffHour < 24) return `${diffHour} hour${diffHour === 1 ? "" : "s"} ago`;
+	return date.toLocaleDateString();
+}
+/** Get auto-save status label. */
+function getAutoSaveStatusLabel(status) {
+	return {
+		idle: "Ready",
+		saving: "Saving...",
+		saved: "Saved",
+		error: "Save failed"
+	}[status];
+}
+/** Get storage size used by auto-save (bytes). */
+function getAutoSaveStorageSize(storageKey = DEFAULT_STORAGE_KEY) {
+	try {
+		const data = localStorage.getItem(storageKey);
+		if (!data) return 0;
+		return new Blob([data]).size;
+	} catch {
+		return 0;
+	}
+}
+/** Format storage size for display. */
+function formatStorageSize(bytes) {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+	return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+/** Check whether auto-save is supported. */
+function isAutoSaveSupported() {
+	return isLocalStorageAvailable();
+}
+//#endregion
+export { AutoSaveManager, formatLastSaveTime, formatStorageSize, getAutoSaveStatusLabel, getAutoSaveStorageSize, isAutoSaveSupported };

package/dist/managers/ClipboardManager.d.ts

@@ -0,0 +1,31 @@
+import { document_d_exports } from "../types/document.js";
+
+//#region src/managers/ClipboardManager.d.ts
+/** Selection data for clipboard operations. */
+type ClipboardSelection = {
+  text: string;
+  runs: document_d_exports.Run[];
+  startParagraphIndex: number;
+  startRunIndex: number;
+  startOffset: number;
+  endParagraphIndex: number;
+  endRunIndex: number;
+  endOffset: number;
+  isMultiParagraph: boolean;
+};
+/**
+ * Convert a CSS color string (rgb/rgba/hex) to a 6-char uppercase hex string.
+ *
+ * NOTE: This parses CSS color *strings*, unlike a numeric-component
+ * `rgbToHex(r, g, b)` helper.
+ */
+declare function cssColorToHex(color: string): string | null;
+/** Extract formatting from an HTML element's computed styles. */
+declare function extractFormattingFromElement(element: HTMLElement): document_d_exports.TextFormatting | undefined;
+/** Get selected runs from the current DOM selection. */
+declare function getSelectionRuns(): document_d_exports.Run[];
+/** Create a ClipboardSelection from the current DOM selection. */
+declare function createSelectionFromDOM(): ClipboardSelection | null;
+declare const rgbToHex: typeof cssColorToHex;
+//#endregion
+export { ClipboardSelection, createSelectionFromDOM, cssColorToHex, extractFormattingFromElement, getSelectionRuns, rgbToHex };

package/dist/managers/ClipboardManager.js

@@ -0,0 +1,147 @@
+//#region src/managers/ClipboardManager.ts
+/**
+* Convert a CSS color string (rgb/rgba/hex) to a 6-char uppercase hex string.
+*
+* NOTE: This parses CSS color *strings*, unlike a numeric-component
+* `rgbToHex(r, g, b)` helper.
+*/
+function cssColorToHex(color) {
+	if (!color || color === "transparent" || color === "inherit") return null;
+	if (color.startsWith("#")) return color.slice(1).toUpperCase();
+	const rgbMatch = /rgba?\((?<r>\d+),\s*(?<g>\d+),\s*(?<b>\d+)/u.exec(color);
+	if (rgbMatch?.groups) {
+		const { r, g, b } = rgbMatch.groups;
+		if (r === void 0 || g === void 0 || b === void 0) return null;
+		const rHex = Number.parseInt(r, 10).toString(16).padStart(2, "0");
+		const gHex = Number.parseInt(g, 10).toString(16).padStart(2, "0");
+		const bHex = Number.parseInt(b, 10).toString(16).padStart(2, "0");
+		return (rHex + gHex + bHex).toUpperCase();
+	}
+	return null;
+}
+/** Extract formatting from an HTML element's computed styles. */
+function extractFormattingFromElement(element) {
+	const style = window.getComputedStyle(element);
+	const formatting = {};
+	if (style.fontWeight === "bold" || Number.parseInt(style.fontWeight, 10) >= 700) formatting.bold = true;
+	if (style.fontStyle === "italic") formatting.italic = true;
+	const textDecoration = style.textDecoration || style.textDecorationLine || "";
+	if (textDecoration.includes("underline")) formatting.underline = { style: "single" };
+	if (textDecoration.includes("line-through")) formatting.strike = true;
+	const fontSize = Number.parseFloat(style.fontSize);
+	if (!Number.isNaN(fontSize) && fontSize > 0) formatting.fontSize = Math.round(fontSize / 1.333 * 2);
+	const fontFamily = style.fontFamily.replace(/["']/gu, "").split(",")[0]?.trim();
+	if (fontFamily) formatting.fontFamily = { ascii: fontFamily };
+	const color = style.color;
+	if (color && color !== "rgb(0, 0, 0)") {
+		const hex = cssColorToHex(color);
+		if (hex) formatting.color = { rgb: hex };
+	}
+	const bgColor = style.backgroundColor;
+	if (bgColor && bgColor !== "transparent" && bgColor !== "rgba(0, 0, 0, 0)") {
+		const hex = cssColorToHex(bgColor);
+		if (hex) formatting.shading = { fill: { rgb: hex } };
+	}
+	return Object.keys(formatting).length > 0 ? formatting : void 0;
+}
+/** Get selected text from a run element, considering partial selection. */
+function getSelectedTextFromRun(runEl, range) {
+	const runRange = document.createRange();
+	runRange.selectNodeContents(runEl);
+	const startInRun = range.compareBoundaryPoints(Range.START_TO_START, runRange) >= 0 && range.compareBoundaryPoints(Range.START_TO_END, runRange) <= 0;
+	const endInRun = range.compareBoundaryPoints(Range.END_TO_START, runRange) >= 0 && range.compareBoundaryPoints(Range.END_TO_END, runRange) <= 0;
+	if (startInRun && endInRun) return range.toString();
+	if (startInRun) {
+		const tempRange = document.createRange();
+		tempRange.setStart(range.startContainer, range.startOffset);
+		tempRange.setEnd(runRange.endContainer, runRange.endOffset);
+		return tempRange.toString();
+	}
+	if (endInRun) {
+		const tempRange = document.createRange();
+		tempRange.setStart(runRange.startContainer, runRange.startOffset);
+		tempRange.setEnd(range.endContainer, range.endOffset);
+		return tempRange.toString();
+	}
+	if (range.intersectsNode(runEl)) return runEl.textContent ?? "";
+	return "";
+}
+/** Find the paragraph element containing a node. */
+function findParagraphElement(node) {
+	let current = node;
+	while (current) {
+		if (current instanceof HTMLElement && current.hasAttribute("data-paragraph-index")) return current;
+		current = current.parentNode;
+	}
+	return null;
+}
+/** Get selected runs from the current DOM selection. */
+function getSelectionRuns() {
+	const selection = window.getSelection();
+	if (!selection || selection.isCollapsed) return [];
+	const runs = [];
+	const range = selection.getRangeAt(0);
+	const container = range.commonAncestorContainer;
+	const containerElement = container instanceof HTMLElement ? container : container.parentElement;
+	if (!containerElement) return runs;
+	const runElements = containerElement.querySelectorAll(".docx-run");
+	for (const runEl of runElements) {
+		if (!(runEl instanceof HTMLElement) || !range.intersectsNode(runEl)) continue;
+		const text = getSelectedTextFromRun(runEl, range);
+		if (!text) continue;
+		const formatting = extractFormattingFromElement(runEl);
+		const run = formatting ? {
+			type: "run",
+			formatting,
+			content: [{
+				type: "text",
+				text
+			}]
+		} : {
+			type: "run",
+			content: [{
+				type: "text",
+				text
+			}]
+		};
+		runs.push(run);
+	}
+	if (runs.length === 0) {
+		const selectedText = selection.toString();
+		if (selectedText) runs.push({
+			type: "run",
+			content: [{
+				type: "text",
+				text: selectedText
+			}]
+		});
+	}
+	return runs;
+}
+/** Create a ClipboardSelection from the current DOM selection. */
+function createSelectionFromDOM() {
+	const selection = window.getSelection();
+	if (!selection || selection.isCollapsed) return null;
+	const runs = getSelectionRuns();
+	if (runs.length === 0) return null;
+	const text = selection.toString();
+	const range = selection.getRangeAt(0);
+	const startPara = findParagraphElement(range.startContainer);
+	const endPara = findParagraphElement(range.endContainer);
+	const startParagraphIndex = startPara ? Number.parseInt(startPara.getAttribute("data-paragraph-index") ?? "0", 10) : 0;
+	const endParagraphIndex = endPara ? Number.parseInt(endPara.getAttribute("data-paragraph-index") ?? "0", 10) : 0;
+	return {
+		text,
+		runs,
+		startParagraphIndex,
+		startRunIndex: 0,
+		startOffset: range.startOffset,
+		endParagraphIndex,
+		endRunIndex: 0,
+		endOffset: range.endOffset,
+		isMultiParagraph: startParagraphIndex !== endParagraphIndex
+	};
+}
+const rgbToHex = cssColorToHex;
+//#endregion
+export { createSelectionFromDOM, cssColorToHex, extractFormattingFromElement, getSelectionRuns, rgbToHex };

package/dist/paged-layout/rangeProjection.d.ts

@@ -25,6 +25,28 @@ type RangeProjectionContext = {
  * left margin is fixed, so this value holds steady as text is edited.
  */
 declare const measureContentLeft: (pagesContainer: HTMLElement, zoom: number) => number | null;
+/**
+ * One page's body-content vertical extent in container space. `.layout-page-content`
+ * is inset by the page margins, so its box excludes the header/footer and the
+ * inter-page gap — exactly the region a gutter rail is allowed to paint over.
+ */
+type PageContentBand = {
+  /** 0-based page index (from `data-page-number` minus one). */pageIndex: number; /** Top of the body content area, container space. */
+  top: number; /** Bottom of the body content area, container space. */
+  bottom: number;
+};
+/**
+ * Left-margin geometry the block-directive rails need in one measurement pass:
+ * the text-column left edge (rail anchor), the usable left-margin width (gutter
+ * budget), and each page's body-content band (so a rail can be clipped per page
+ * instead of running across page breaks). Measured O(pages), never per-range.
+ */
+type DirectiveGutterGeometry = {
+  /** Text-column left edge, container space. Rails anchor here. */contentLeft: number; /** Usable left-margin width: `contentLeft - pageLeftEdge`. Drives the budget. */
+  marginWidth: number; /** Per-page body-content vertical bands, in document order. */
+  pageBands: PageContentBand[];
+};
+declare const measureDirectiveGutter: (pagesContainer: HTMLElement, zoom: number) => DirectiveGutterGeometry | null;
 /**
  * Computed text style of the painted run at a PM position. Overlays
  * that paint substituted text over the pages (template fill preview,
@@ -48,4 +70,4 @@ type ProjectedRunFont = {
 declare const collectRunFontsAtPmPositions: (pagesContainer: HTMLElement, positions: readonly number[]) => Map<number, ProjectedRunFont>;
 declare const projectRangesToRects: <T extends ProjectableRange>(ranges: readonly T[], ctx: RangeProjectionContext) => Promise<ProjectedRange<T>[]>;
 //#endregion
-export { ProjectableRange, ProjectedRange, ProjectedRunFont, RangeProjectionContext, collectRunFontsAtPmPositions, measureContentLeft, projectRangesToRects };
+export { DirectiveGutterGeometry, PageContentBand, ProjectableRange, ProjectedRange, ProjectedRunFont, RangeProjectionContext, collectRunFontsAtPmPositions, measureContentLeft, measureDirectiveGutter, projectRangesToRects };