@stll/folio-core 0.0.1-placeholder.0 → 0.1.1

package/dist/prosemirror/utils/tabCalculator.js

@@ -0,0 +1,137 @@
+//#region src/prosemirror/utils/tabCalculator.ts
+/** Default tab interval: 720 twips = 0.5 inch */
+const DEFAULT_TAB_INTERVAL_TWIPS = 720;
+/** Twips per inch */
+const TWIPS_PER_INCH = 1440;
+/** Pixels per inch (96 dpi standard for CSS) */
+const PIXELS_PER_INCH = 96;
+/**
+* Convert twips to pixels
+* @param twips - Value in twips (1/1440 inch)
+* @returns Value in pixels (at 96 dpi)
+*/
+function twipsToPixels(twips) {
+	return twips / TWIPS_PER_INCH * 96;
+}
+/**
+* Convert pixels to twips
+* @param pixels - Value in pixels (at 96 dpi)
+* @returns Value in twips (1/1440 inch)
+*/
+function pixelsToTwips(pixels) {
+	return pixels / 96 * TWIPS_PER_INCH;
+}
+/**
+* Compute the list of effective tab stops for a paragraph
+*
+* Merges explicit stops with default stops at regular intervals.
+* Filters out stops that fall before the left indent.
+*
+* @param context - Tab context with explicit stops and settings
+* @returns Sorted array of tab stops in twips
+*/
+function computeTabStops(context) {
+	const { explicitStops = [], defaultTabInterval = 720, leftIndent = 0 } = context;
+	const validExplicitStops = explicitStops.filter((stop) => stop.val !== "clear").filter((stop) => stop.pos >= leftIndent);
+	const clearPositions = explicitStops.filter((stop) => stop.val === "clear").map((stop) => stop.pos);
+	let maxExplicit = 0;
+	for (const stop of validExplicitStops) maxExplicit = Math.max(maxExplicit, stop.pos);
+	const stops = [...validExplicitStops];
+	if (leftIndent > 0 && !validExplicitStops.some((s) => s.pos <= leftIndent)) {
+		if (!clearPositions.some((p) => Math.abs(p - leftIndent) < 20)) stops.push({
+			val: "start",
+			pos: leftIndent,
+			leader: "none"
+		});
+	}
+	let pos = maxExplicit > 0 ? Math.max(maxExplicit, leftIndent) : leftIndent;
+	const limitPos = leftIndent + 14400;
+	while (pos < limitPos) {
+		pos += defaultTabInterval;
+		let hasExplicitStop = false;
+		for (const stop of validExplicitStops) if (Math.abs(stop.pos - pos) < 20) {
+			hasExplicitStop = true;
+			break;
+		}
+		let hasClearStop = false;
+		for (const clearPos of clearPositions) if (Math.abs(clearPos - pos) < 20) {
+			hasClearStop = true;
+			break;
+		}
+		const isAtLeftIndent = leftIndent > 0 && Math.abs(pos - leftIndent) < 20;
+		if (!hasExplicitStop && !hasClearStop && !isAtLeftIndent) stops.push({
+			val: "start",
+			pos,
+			leader: "none"
+		});
+	}
+	return stops.toSorted((a, b) => a.pos - b.pos);
+}
+/**
+* Calculate the width of a tab character.
+*
+* Finds the next tab stop after the current position and computes the width
+* needed to reach it. For `end`/`center`/`decimal` stops the content after the
+* tab is anchored against the stop, so the caller supplies its measured width
+* via {@link TabFollowingContent}.
+*
+* @param currentXPx - Current horizontal position in pixels (from the content
+*   area's left edge — the same origin tab stop positions are measured from)
+* @param context - Tab context with stops and settings
+* @param following - Measured widths of the content after the tab
+* @returns Tab width result with width in pixels
+*/
+function calculateTabWidth(currentXPx, context, following = {}) {
+	const { defaultTabInterval = 720 } = context;
+	const currentXTwips = pixelsToTwips(currentXPx);
+	const nextStop = computeTabStops(context).find((stop) => stop.pos > currentXTwips);
+	if (!nextStop) {
+		const defaultTabPx = twipsToPixels(defaultTabInterval);
+		let tabWidth = defaultTabPx - currentXPx % defaultTabPx;
+		if (tabWidth <= 0) tabWidth = defaultTabPx;
+		return {
+			width: tabWidth,
+			alignment: "default"
+		};
+	}
+	let width = twipsToPixels(nextStop.pos) - currentXPx;
+	if (nextStop.val === "center") width -= (following.followingWidth ?? 0) / 2;
+	else if (nextStop.val === "end") width -= following.followingWidth ?? 0;
+	else if (nextStop.val === "decimal") width -= following.decimalPrefixWidth ?? 0;
+	else if (nextStop.val === "bar") return {
+		width: 0,
+		...nextStop.leader !== void 0 ? { leader: nextStop.leader } : {},
+		alignment: "bar"
+	};
+	if (width < 1) {
+		const defaultTabPx = twipsToPixels(defaultTabInterval);
+		let fallbackWidth = defaultTabPx - currentXPx % defaultTabPx;
+		if (fallbackWidth <= 0) fallbackWidth = defaultTabPx;
+		return {
+			width: fallbackWidth,
+			alignment: "default"
+		};
+	}
+	return {
+		width,
+		...nextStop.leader !== void 0 ? { leader: nextStop.leader } : {},
+		alignment: nextStop.val
+	};
+}
+/**
+* Calculate tab width with simple default stops
+*
+* Simplified version for basic tab rendering without explicit stops.
+* Uses the default 0.5 inch (48px) tab interval.
+*
+* @param currentXPx - Current horizontal position in pixels
+* @returns Width of the tab in pixels
+*/
+function calculateSimpleTabWidth(currentXPx) {
+	const defaultTabPx = twipsToPixels(720);
+	let tabWidth = defaultTabPx - currentXPx % defaultTabPx;
+	if (tabWidth < defaultTabPx / 4) tabWidth += defaultTabPx;
+	return tabWidth;
+}
+//#endregion
+export { DEFAULT_TAB_INTERVAL_TWIPS, PIXELS_PER_INCH, TWIPS_PER_INCH, calculateSimpleTabWidth, calculateTabWidth, computeTabStops, pixelsToTwips, twipsToPixels };

package/dist/prosemirror/validation.d.ts

@@ -0,0 +1,20 @@
+import { Node } from "prosemirror-model";
+
+//#region src/prosemirror/validation.d.ts
+type ProseMirrorDocumentValidationIssue = {
+  path: string;
+  message: string;
+};
+type ValidateProseMirrorDocumentResult = {
+  valid: boolean;
+  issues: ProseMirrorDocumentValidationIssue[];
+};
+declare class ProseMirrorDocumentValidationError extends Error {
+  readonly issues: ProseMirrorDocumentValidationIssue[];
+  constructor(context: string, issues: ProseMirrorDocumentValidationIssue[]);
+}
+declare const validateProseMirrorDocument: (doc: Node) => ValidateProseMirrorDocumentResult;
+declare const assertValidProseMirrorDocument: (doc: Node, context: string) => void;
+declare const formatProseMirrorDocumentIssues: (issues: ProseMirrorDocumentValidationIssue[]) => string[];
+//#endregion
+export { ProseMirrorDocumentValidationError, ProseMirrorDocumentValidationIssue, ValidateProseMirrorDocumentResult, assertValidProseMirrorDocument, formatProseMirrorDocumentIssues, validateProseMirrorDocument };

package/dist/prosemirror/validation.js

@@ -0,0 +1,177 @@
+import { readBlockSdtAttrs, readCharacterSpacingMarkAttrs, readCharacterStyleMarkAttrs, readCommentMarkAttrs, readEmphasisMarkAttrs, readFieldAttrs, readFontFamilyMarkAttrs, readFontSizeMarkAttrs, readFootnoteRefMarkAttrs, readHardBreakAttrs, readHighlightMarkAttrs, readHyperlinkMarkAttrs, readImageAttrs, readMathAttrs, readParagraphAttrs, readRunFormattingOverrideMarkAttrs, readRunShadingMarkAttrs, readSdtAttrs, readShapeAttrs, readStrikeMarkAttrs, readTableAttrs, readTableCellAttrs, readTableRowAttrs, readTextBoxAttrs, readTextColorMarkAttrs, readTextEffectMarkAttrs, readTrackedChangeMarkAttrs, readUnderlineMarkAttrs } from "./attrs/index.js";
+//#region src/prosemirror/validation.ts
+var ProseMirrorDocumentValidationError = class extends Error {
+	issues;
+	constructor(context, issues) {
+		super(`${context}:\n${formatProseMirrorDocumentIssues(issues).join("\n")}`);
+		this.name = "ProseMirrorDocumentValidationError";
+		this.issues = issues;
+	}
+};
+const validDocumentCache = /* @__PURE__ */ new WeakSet();
+const validNodeCache = /* @__PURE__ */ new WeakSet();
+const validateProseMirrorDocument = (doc) => {
+	const issues = [];
+	if (doc.type.name !== "doc") issues.push({
+		path: "doc.type.name",
+		message: `Expected doc, got ${doc.type.name}.`
+	});
+	validateNode(doc, "doc", issues);
+	return {
+		valid: issues.length === 0,
+		issues
+	};
+};
+const assertValidProseMirrorDocument = (doc, context) => {
+	if (validDocumentCache.has(doc)) return;
+	const validation = validateProseMirrorDocument(doc);
+	if (validation.valid) {
+		validDocumentCache.add(doc);
+		return;
+	}
+	throw new ProseMirrorDocumentValidationError(context, validation.issues);
+};
+const formatProseMirrorDocumentIssues = (issues) => issues.map((issue) => `ProseMirror document error at ${issue.path}: ${issue.message}`);
+const validateNode = (node, path, issues) => {
+	if (validNodeCache.has(node)) return;
+	const issueCountBeforeNode = issues.length;
+	validateNodeAttrs(node, path, issues);
+	validateMarks(node.marks, path, issues);
+	node.forEach((child, _offset, index) => {
+		validateNode(child, `${path}.content[${index}]`, issues);
+	});
+	if (issues.length === issueCountBeforeNode) validNodeCache.add(node);
+};
+const validateNodeAttrs = (node, path, issues) => {
+	switch (node.type.name) {
+		case "doc":
+		case "text":
+		case "horizontalRule":
+		case "pageBreak":
+		case "tab": return;
+		case "hardBreak":
+			appendAttrIssues(path, readHardBreakAttrs(node), issues);
+			return;
+		case "paragraph":
+			appendAttrIssues(path, readParagraphAttrs(node), issues);
+			return;
+		case "table":
+			appendAttrIssues(path, readTableAttrs(node), issues);
+			return;
+		case "tableRow":
+			appendAttrIssues(path, readTableRowAttrs(node), issues);
+			return;
+		case "tableCell":
+		case "tableHeader":
+			appendAttrIssues(path, readTableCellAttrs(node), issues);
+			return;
+		case "image":
+			appendAttrIssues(path, readImageAttrs(node), issues);
+			return;
+		case "field":
+			appendAttrIssues(path, readFieldAttrs(node), issues);
+			return;
+		case "math":
+			appendAttrIssues(path, readMathAttrs(node), issues);
+			return;
+		case "sdt":
+			appendAttrIssues(path, readSdtAttrs(node), issues);
+			return;
+		case "blockSdt":
+			appendAttrIssues(path, readBlockSdtAttrs(node), issues);
+			for (let i = 0; i < node.childCount; i += 1) validateNode(node.child(i), `${path}.content[${i}]`, issues);
+			return;
+		case "shape":
+			appendAttrIssues(path, readShapeAttrs(node), issues);
+			return;
+		case "textBox":
+			appendAttrIssues(path, readTextBoxAttrs(node), issues);
+			return;
+		default: issues.push({
+			path: `${path}.type.name`,
+			message: `Unsupported ProseMirror node type ${node.type.name}.`
+		});
+	}
+};
+const validateMarks = (marks, path, issues) => {
+	for (const [index, mark] of marks.entries()) {
+		const markPath = `${path}.marks[${index}]`;
+		switch (mark.type.name) {
+			case "bold":
+			case "italic":
+			case "subscript":
+			case "superscript":
+			case "allCaps":
+			case "smallCaps":
+			case "emboss":
+			case "imprint":
+			case "hidden":
+			case "textShadow":
+			case "textOutline":
+			case "rtl": continue;
+			case "textEffect":
+				appendAttrIssues(markPath, readTextEffectMarkAttrs(mark), issues);
+				continue;
+			case "underline":
+				appendAttrIssues(markPath, readUnderlineMarkAttrs(mark), issues);
+				continue;
+			case "strike":
+				appendAttrIssues(markPath, readStrikeMarkAttrs(mark), issues);
+				continue;
+			case "textColor":
+				appendAttrIssues(markPath, readTextColorMarkAttrs(mark), issues);
+				continue;
+			case "highlight":
+				appendAttrIssues(markPath, readHighlightMarkAttrs(mark), issues);
+				continue;
+			case "runShading":
+				appendAttrIssues(markPath, readRunShadingMarkAttrs(mark), issues);
+				continue;
+			case "fontSize":
+				appendAttrIssues(markPath, readFontSizeMarkAttrs(mark), issues);
+				continue;
+			case "fontFamily":
+				appendAttrIssues(markPath, readFontFamilyMarkAttrs(mark), issues);
+				continue;
+			case "characterSpacing":
+				appendAttrIssues(markPath, readCharacterSpacingMarkAttrs(mark), issues);
+				continue;
+			case "characterStyle":
+				appendAttrIssues(markPath, readCharacterStyleMarkAttrs(mark), issues);
+				continue;
+			case "emphasisMark":
+				appendAttrIssues(markPath, readEmphasisMarkAttrs(mark), issues);
+				continue;
+			case "footnoteRef":
+				appendAttrIssues(markPath, readFootnoteRefMarkAttrs(mark), issues);
+				continue;
+			case "comment":
+				appendAttrIssues(markPath, readCommentMarkAttrs(mark), issues);
+				continue;
+			case "insertion":
+			case "deletion":
+				appendAttrIssues(markPath, readTrackedChangeMarkAttrs(mark), issues);
+				continue;
+			case "runFormattingOverride":
+				appendAttrIssues(markPath, readRunFormattingOverrideMarkAttrs(mark), issues);
+				continue;
+			case "hyperlink":
+				appendAttrIssues(markPath, readHyperlinkMarkAttrs(mark), issues);
+				continue;
+			default: issues.push({
+				path: `${markPath}.type.name`,
+				message: `Unsupported ProseMirror mark type ${mark.type.name}.`
+			});
+		}
+	}
+};
+const appendAttrIssues = (path, result, issues) => {
+	if (result.ok) return;
+	for (const issue of result.issues) issues.push(withPathPrefix(path, issue));
+};
+const withPathPrefix = (prefix, issue) => ({
+	path: `${prefix}.${issue.path}`,
+	message: issue.message
+});
+//#endregion
+export { ProseMirrorDocumentValidationError, assertValidProseMirrorDocument, formatProseMirrorDocumentIssues, validateProseMirrorDocument };

package/dist/server.d.ts

@@ -0,0 +1,7 @@
+import { FolioAIBlock, FolioAIBlockAnchor, FolioAIBlockKind, FolioAIBlockPreviewRun, FolioAIComment, FolioAIEditApplyMode, FolioAIEditApplyResult, FolioAIEditOperation, FolioAIEditSnapshot } from "./ai-edits/types.js";
+import { ApplyFolioAIEditsToBufferOptions, ApplyFolioAIEditsToBufferResult, FolioApplyOperationsOptions, FolioDocxReviewer, FolioDocxReviewerOptions, FolioReviewChange, FolioReviewChangeFilter, FolioReviewChangeKind, FolioReviewComment, FolioReviewCommentFilter, FolioReviewCommentReply, FolioReviewReplyInput, applyFolioAIEditsToBuffer } from "./ai-edits/headless.js";
+import { DeriveBlockIdInput, FolioBlockId, deriveBlockId, getFolioParaIdFromBlockId, isFolioBlockId, isSequentialFolioBlockId } from "./types/block-id.js";
+import { CreateCommentReplyInput, replyToComment } from "./docx/replyToComment.js";
+import { createDocx } from "./docx/rezip.js";
+import { CreateEmptyDocumentOptions, createEmptyDocument } from "./utils/createDocument.js";
+export { type ApplyFolioAIEditsToBufferOptions, type ApplyFolioAIEditsToBufferResult, type CreateCommentReplyInput, type CreateEmptyDocumentOptions, type DeriveBlockIdInput, type FolioAIBlock, type FolioAIBlockAnchor, type FolioAIBlockKind, type FolioAIBlockPreviewRun, type FolioAIComment, type FolioAIEditApplyMode, type FolioAIEditApplyResult, type FolioAIEditOperation, type FolioAIEditSnapshot, type FolioApplyOperationsOptions, type FolioBlockId, FolioDocxReviewer, type FolioDocxReviewerOptions, type FolioReviewChange, type FolioReviewChangeFilter, type FolioReviewChangeKind, type FolioReviewComment, type FolioReviewCommentFilter, type FolioReviewCommentReply, type FolioReviewReplyInput, applyFolioAIEditsToBuffer, createDocx, createEmptyDocument, deriveBlockId, getFolioParaIdFromBlockId, isFolioBlockId, isSequentialFolioBlockId, replyToComment };

package/dist/server.js

@@ -0,0 +1,6 @@
+import { createEmptyDocument } from "./utils/createDocument.js";
+import { createDocx } from "./docx/rezip.js";
+import { deriveBlockId, getFolioParaIdFromBlockId, isFolioBlockId, isSequentialFolioBlockId } from "./types/block-id.js";
+import { replyToComment } from "./docx/replyToComment.js";
+import { FolioDocxReviewer, applyFolioAIEditsToBuffer } from "./ai-edits/headless.js";
+export { FolioDocxReviewer, applyFolioAIEditsToBuffer, createDocx, createEmptyDocument, deriveBlockId, getFolioParaIdFromBlockId, isFolioBlockId, isSequentialFolioBlockId, replyToComment };

package/dist/style-engine/index.d.ts

@@ -0,0 +1,3 @@
+import { ResolvedParagraphStyle } from "../prosemirror/styles/styleResolver.js";
+import { StyleEngine, StyleEngineCacheStats, StyleEngineOptions, createStyleEngine } from "./styleEngine.js";
+export { type ResolvedParagraphStyle, type StyleEngine, type StyleEngineCacheStats, type StyleEngineOptions, createStyleEngine };

package/dist/style-engine/index.js

@@ -0,0 +1,2 @@
+import { createStyleEngine } from "./styleEngine.js";
+export { createStyleEngine };

package/dist/style-engine/styleEngine.d.ts

@@ -0,0 +1,67 @@
+import { document_d_exports } from "../types/document.js";
+import { ResolvedParagraphStyle } from "../prosemirror/styles/styleResolver.js";
+
+//#region src/style-engine/styleEngine.d.ts
+/** Engine construction options. */
+type StyleEngineOptions = {
+  /**
+   * Toggle the memoization layer.
+   *
+   * Defaults to `true`. Set to `false` to force every call through the
+   * underlying {@link StyleResolver}; useful in tests where stale-cache
+   * bugs could mask real regressions, and for diagnosing cache-related
+   * behaviour without rebuilding the engine.
+   */
+  cache?: boolean;
+};
+/** Lightweight observability for cache effectiveness. */
+type StyleEngineCacheStats = {
+  hits: number;
+  misses: number; /** Total entries across all internal caches. */
+  size: number;
+};
+/**
+ * Cached, explicit style cascade engine.
+ *
+ * The engine exposes the same surface as {@link StyleResolver} for the
+ * methods folio currently consumes, plus cache controls. Returned
+ * objects are shared between cache hits — treat them as immutable.
+ */
+type StyleEngine = {
+  /** Look up a single named style by id. */getStyle: (styleId: string) => document_d_exports.Style | undefined; /** True if a style with the given id is registered. */
+  hasStyle: (styleId: string) => boolean; /** Return the document-wide defaults (`w:docDefaults`). */
+  getDocDefaults: () => document_d_exports.DocDefaults | undefined; /** The style flagged `w:default="1"` for paragraphs, else "Normal". */
+  getDefaultParagraphStyle: () => document_d_exports.Style | undefined; /** The style flagged `w:default="1"` for character styles. */
+  getDefaultCharacterStyle: () => document_d_exports.Style | undefined; /** The style flagged `w:default="1"` for tables. */
+  getDefaultTableStyle: () => document_d_exports.Style | undefined; /** All visible paragraph styles, sorted for toolbar use. */
+  getParagraphStyles: () => document_d_exports.Style[]; /** All visible table styles, sorted for the table-style gallery. */
+  getTableStyles: () => document_d_exports.Style[];
+  /**
+   * Resolve the full paragraph cascade for a given styleId.
+   * Returned object is cached and must not be mutated.
+   */
+  resolveParagraphStyle: (styleId: string | undefined | null) => ResolvedParagraphStyle;
+  /**
+   * Resolve a run/character style with docDefaults applied.
+   * Returns `undefined` when the cascade yields nothing.
+   */
+  resolveRunStyle: (styleId: string | undefined | null) => document_d_exports.TextFormatting | undefined;
+  /**
+   * Return a run style's own properties without docDefaults applied —
+   * used when the caller has already merged docDefaults via the
+   * paragraph cascade and would otherwise double-apply font defaults.
+   */
+  getRunStyleOwnProperties: (styleId: string | undefined | null) => document_d_exports.TextFormatting | undefined; /** Drop every memoized cascade result. */
+  invalidate: () => void; /** Inspect cache effectiveness (hits, misses, current size). */
+  stats: () => StyleEngineCacheStats;
+};
+/**
+ * Build a {@link StyleEngine} from parsed style definitions.
+ *
+ * @param styleDefinitions - The parsed `styles.xml` package, or `undefined`
+ *   for documents without a styles part.
+ * @param options - Engine-level toggles, see {@link StyleEngineOptions}.
+ */
+declare function createStyleEngine(styleDefinitions: document_d_exports.StyleDefinitions | undefined, options?: StyleEngineOptions): StyleEngine;
+//#endregion
+export { StyleEngine, StyleEngineCacheStats, StyleEngineOptions, createStyleEngine };

package/dist/style-engine/styleEngine.js

@@ -0,0 +1,70 @@
+import { createStyleResolver } from "../prosemirror/styles/styleResolver.js";
+//#region src/style-engine/styleEngine.ts
+/**
+* Sentinel key used for null / undefined styleId queries so that
+* {@link Map} lookups distinguish "cached an undefined result" from
+* "never queried" without storing JS `undefined` as a key.
+*/
+const DEFAULT_KEY = "\0__default__";
+function cacheKey(styleId) {
+	if (styleId === void 0 || styleId === null || styleId === "") return DEFAULT_KEY;
+	return styleId;
+}
+/**
+* Build a {@link StyleEngine} from parsed style definitions.
+*
+* @param styleDefinitions - The parsed `styles.xml` package, or `undefined`
+*   for documents without a styles part.
+* @param options - Engine-level toggles, see {@link StyleEngineOptions}.
+*/
+function createStyleEngine(styleDefinitions, options) {
+	const resolver = createStyleResolver(styleDefinitions);
+	const cacheEnabled = options?.cache ?? true;
+	const paragraphCache = /* @__PURE__ */ new Map();
+	const runCache = /* @__PURE__ */ new Map();
+	const ownPropsCache = /* @__PURE__ */ new Map();
+	let hits = 0;
+	let misses = 0;
+	const memoize = (cache, key, compute) => {
+		if (!cacheEnabled) {
+			misses += 1;
+			return compute();
+		}
+		const cached = cache.get(key);
+		if (cached !== void 0) {
+			hits += 1;
+			return cached.value;
+		}
+		misses += 1;
+		const value = compute();
+		cache.set(key, { value });
+		return value;
+	};
+	return {
+		getStyle: (styleId) => resolver.getStyle(styleId),
+		hasStyle: (styleId) => resolver.hasStyle(styleId),
+		getDocDefaults: () => resolver.getDocDefaults(),
+		getDefaultParagraphStyle: () => resolver.getDefaultParagraphStyle(),
+		getDefaultCharacterStyle: () => resolver.getDefaultCharacterStyle(),
+		getDefaultTableStyle: () => resolver.getDefaultTableStyle(),
+		getParagraphStyles: () => resolver.getParagraphStyles(),
+		getTableStyles: () => resolver.getTableStyles(),
+		resolveParagraphStyle: (styleId) => memoize(paragraphCache, cacheKey(styleId), () => resolver.resolveParagraphStyle(styleId)),
+		resolveRunStyle: (styleId) => memoize(runCache, cacheKey(styleId), () => resolver.resolveRunStyle(styleId)),
+		getRunStyleOwnProperties: (styleId) => memoize(ownPropsCache, cacheKey(styleId), () => resolver.getRunStyleOwnProperties(styleId)),
+		invalidate: () => {
+			paragraphCache.clear();
+			runCache.clear();
+			ownPropsCache.clear();
+			hits = 0;
+			misses = 0;
+		},
+		stats: () => ({
+			hits,
+			misses,
+			size: paragraphCache.size + runCache.size + ownPropsCache.size
+		})
+	};
+}
+//#endregion
+export { createStyleEngine };

package/dist/types/block-id.d.ts

@@ -0,0 +1,66 @@
+//#region src/types/block-id.d.ts
+/**
+ * Single source of truth for folio block ids.
+ *
+ * Both the in-browser editor snapshot (`createFolioAIEditSnapshot`)
+ * and the server-side DOCX extractor (`apps/api/.../docx-blocks.ts`)
+ * import {@link deriveBlockId} so a citation written by the server
+ * resolves in the editor without a separate mapping table. Any other
+ * way of minting an id — `b-${n}`, `${idx}`, hand-rolled prefixes —
+ * is by definition unable to produce a {@link FolioBlockId}: the
+ * branded type makes the divergence a compile-time error rather
+ * than a silent "scrollToBlock retries 20 times and gives up".
+ *
+ * Two id shapes are allowed:
+ * - Word's `w14:paraId` (or any non-empty allocator-generated id),
+ *   surfaced verbatim when the source paragraph carries one.
+ * - A zero-padded `seq-NNNN` fallback derived from document order,
+ *   used when the paragraph has no paraId or the paraId collides
+ *   with one already taken in the same derivation pass.
+ */
+type FolioBlockId = string & {
+  readonly __brand: "folio.blockId";
+};
+type DeriveBlockIdInput = {
+  /**
+   * Source paragraph's `w14:paraId` (or any equivalent stable id),
+   * or `null` when the paragraph has none.
+   */
+  paraId: string | null; /** 1-based document order for the paragraph being derived. */
+  index: number;
+  /**
+   * Ids already minted in the same derivation pass. Used to bump
+   * the sequential fallback past any collisions (with the source
+   * paraId set OR with previous fallbacks).
+   */
+  taken: ReadonlySet<string>;
+};
+declare const deriveBlockId: ({
+  paraId,
+  index,
+  taken
+}: DeriveBlockIdInput) => FolioBlockId;
+declare const isSequentialFolioBlockId: (id: string) => boolean;
+/**
+ * Extract the paraId an id was derived from, if any. Returns `null`
+ * for sequential fallbacks. Accepts plain `string` so consumers that
+ * have a raw id (snapshot anchors, operation blockIds) can call it
+ * without an upfront brand check.
+ */
+declare const getFolioParaIdFromBlockId: (id: string) => string | null;
+/**
+ * The 1-based document position encoded in a sequential fallback id
+ * (`seq-0011` -> 11), or `null` for paraId-backed ids. The number is
+ * the block's position in the same non-empty-block walk both the
+ * server DOCX extractor and `createFolioAIEditSnapshot` use, so it
+ * indexes a snapshot's ordered `blocks` array directly.
+ */
+declare const getSequentialFolioBlockIdIndex: (id: string) => number | null;
+/**
+ * Runtime refinement for ids coming back from the DB / API. Accepts
+ * the same two shapes {@link deriveBlockId} produces and nothing
+ * else — so legacy `b-NNNN` rows stop counting as valid here.
+ */
+declare const isFolioBlockId: (value: unknown) => value is FolioBlockId;
+//#endregion
+export { DeriveBlockIdInput, FolioBlockId, deriveBlockId, getFolioParaIdFromBlockId, getSequentialFolioBlockIdIndex, isFolioBlockId, isSequentialFolioBlockId };

package/dist/types/block-id.js

@@ -0,0 +1,73 @@
+//#region src/types/block-id.ts
+/**
+* Single source of truth for folio block ids.
+*
+* Both the in-browser editor snapshot (`createFolioAIEditSnapshot`)
+* and the server-side DOCX extractor (`apps/api/.../docx-blocks.ts`)
+* import {@link deriveBlockId} so a citation written by the server
+* resolves in the editor without a separate mapping table. Any other
+* way of minting an id — `b-${n}`, `${idx}`, hand-rolled prefixes —
+* is by definition unable to produce a {@link FolioBlockId}: the
+* branded type makes the divergence a compile-time error rather
+* than a silent "scrollToBlock retries 20 times and gives up".
+*
+* Two id shapes are allowed:
+* - Word's `w14:paraId` (or any non-empty allocator-generated id),
+*   surfaced verbatim when the source paragraph carries one.
+* - A zero-padded `seq-NNNN` fallback derived from document order,
+*   used when the paragraph has no paraId or the paraId collides
+*   with one already taken in the same derivation pass.
+*/
+const SEQUENTIAL_BLOCK_ID_PREFIX = "seq-";
+const SEQUENTIAL_BLOCK_ID_PADDING = 4;
+const SEQUENTIAL_BLOCK_ID_PATTERN = /^seq-\d{4,}$/u;
+const formatSequentialBlockId = (index) => `${SEQUENTIAL_BLOCK_ID_PREFIX}${String(index).padStart(SEQUENTIAL_BLOCK_ID_PADDING, "0")}`;
+/**
+* The opaque `FolioBlockId` brand has no constructor; an unchecked
+* cast is the runtime no-op that mints one. Centralising the cast
+* here means every other site can keep `typescript/no-unsafe-type-assertion`
+* on.
+*/
+const brand = (value) => value;
+const deriveBlockId = ({ paraId, index, taken }) => {
+	if (paraId !== null && paraId.length > 0 && !taken.has(paraId)) return brand(paraId);
+	let candidate = index;
+	let formatted = formatSequentialBlockId(candidate);
+	while (taken.has(formatted)) {
+		candidate += 1;
+		formatted = formatSequentialBlockId(candidate);
+	}
+	return brand(formatted);
+};
+const isSequentialFolioBlockId = (id) => SEQUENTIAL_BLOCK_ID_PATTERN.test(id);
+/**
+* Extract the paraId an id was derived from, if any. Returns `null`
+* for sequential fallbacks. Accepts plain `string` so consumers that
+* have a raw id (snapshot anchors, operation blockIds) can call it
+* without an upfront brand check.
+*/
+const getFolioParaIdFromBlockId = (id) => isSequentialFolioBlockId(id) ? null : id;
+/**
+* The 1-based document position encoded in a sequential fallback id
+* (`seq-0011` -> 11), or `null` for paraId-backed ids. The number is
+* the block's position in the same non-empty-block walk both the
+* server DOCX extractor and `createFolioAIEditSnapshot` use, so it
+* indexes a snapshot's ordered `blocks` array directly.
+*/
+const getSequentialFolioBlockIdIndex = (id) => {
+	if (!SEQUENTIAL_BLOCK_ID_PATTERN.test(id)) return null;
+	const index = Number(id.slice(4));
+	return Number.isInteger(index) && index > 0 ? index : null;
+};
+/**
+* Runtime refinement for ids coming back from the DB / API. Accepts
+* the same two shapes {@link deriveBlockId} produces and nothing
+* else — so legacy `b-NNNN` rows stop counting as valid here.
+*/
+const isFolioBlockId = (value) => {
+	if (typeof value !== "string" || value.length === 0) return false;
+	if (value.startsWith(SEQUENTIAL_BLOCK_ID_PREFIX)) return SEQUENTIAL_BLOCK_ID_PATTERN.test(value);
+	return true;
+};
+//#endregion
+export { deriveBlockId, getFolioParaIdFromBlockId, getSequentialFolioBlockIdIndex, isFolioBlockId, isSequentialFolioBlockId };

package/dist/types/colors.d.ts

@@ -0,0 +1,2 @@
+import { BorderSpec, ColorValue, ShadingProperties, ThemeColorSlot } from "@stll/docx-core/model";
+export type { BorderSpec, ColorValue, ShadingProperties, ThemeColorSlot };

package/dist/types/content.d.ts

@@ -0,0 +1,2 @@
+import { BlockContent, BlockSdt, BookmarkEnd, BookmarkStart, BreakContent, Column, Comment, CommentRangeEnd, CommentRangeStart, CommentReference, ComplexField, Deletion, DocumentBody, DrawingContent, Endnote, EndnotePosition, EndnoteProperties, Field, FieldCharContent, FieldType, FooterReference, Footnote, FootnotePosition, FootnoteProperties, HeaderFooter, HeaderFooterType, HeaderReference, Hyperlink, Image, ImageCrop, ImagePadding, ImagePosition, ImageSize, ImageTransform, ImageWrap, InlineSdt, Insertion, InstrTextContent, LineNumberRestart, MathEquation, MoveFrom, MoveFromRangeEnd, MoveFromRangeStart, MoveTo, MoveToRangeEnd, MoveToRangeStart, NoBreakHyphenContent, NoteNumberRestart, NoteReferenceContent, PageOrientation, Paragraph, ParagraphContent, ParagraphPropertyChange, PropertyChangeInfo, Run, RunContent, RunPropertyChange, SdtProperties, SdtType, Section, SectionProperties, SectionStart, Shape, ShapeContent, ShapeFill, ShapeOutline, ShapeTextBody, ShapeType, SimpleField, SoftHyphenContent, SymbolContent, TabContent, Table, TableCell, TableCellPropertyChange, TableRow, TableRowPropertyChange, TableStructuralChangeInfo, TextBox, TextContent, TrackedChangeInfo, TrackedRunChange, VerticalAlign } from "@stll/docx-core/model";
+export type { BlockContent, BlockSdt, BookmarkEnd, BookmarkStart, BreakContent, Column, Comment, CommentRangeEnd, CommentRangeStart, CommentReference, ComplexField, Deletion, DocumentBody, DrawingContent, Endnote, EndnotePosition, EndnoteProperties, Field, FieldCharContent, FieldType, FooterReference, Footnote, FootnotePosition, FootnoteProperties, HeaderFooter, HeaderFooterType, HeaderReference, Hyperlink, Image, ImageCrop, ImagePadding, ImagePosition, ImageSize, ImageTransform, ImageWrap, InlineSdt, Insertion, InstrTextContent, LineNumberRestart, MathEquation, MoveFrom, MoveFromRangeEnd, MoveFromRangeStart, MoveTo, MoveToRangeEnd, MoveToRangeStart, NoBreakHyphenContent, NoteNumberRestart, NoteReferenceContent, PageOrientation, Paragraph, ParagraphContent, ParagraphPropertyChange, PropertyChangeInfo, Run, RunContent, RunPropertyChange, SdtProperties, SdtType, Section, SectionProperties, SectionStart, Shape, ShapeContent, ShapeFill, ShapeOutline, ShapeTextBody, ShapeType, SimpleField, SoftHyphenContent, SymbolContent, TabContent, Table, TableCell, TableCellPropertyChange, TableRow, TableRowPropertyChange, TableStructuralChangeInfo, TextBox, TextContent, TrackedChangeInfo, TrackedRunChange, VerticalAlign };

package/dist/types/document.d.ts

@@ -0,0 +1,7 @@
+export type * from "@stll/docx-core/model";
+
+//#region src/types/document.d.ts
+
+import * as import__stll_docx_core_model from "@stll/docx-core/model";
+//#endregion
+export { import__stll_docx_core_model as document_d_exports };