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

package/dist/docx/parserEnums.js

@@ -0,0 +1,70 @@
+import { BORDER_STYLE_VALUES, CONDITIONAL_STYLE_TYPE_VALUES, EMPHASIS_MARK_VALUES, FIELD_TYPE_VALUES, FLOATING_TABLE_X_SPEC_VALUES, FLOATING_TABLE_Y_SPEC_VALUES, FONT_THEME_VALUES, FRAME_WRAP_VALUES, FRAME_X_ALIGN_VALUES, FRAME_Y_ALIGN_VALUES, HIGHLIGHT_COLOR_VALUES, IMAGE_HORIZONTAL_ALIGNMENT_VALUES, IMAGE_HORIZONTAL_RELATIVE_TO_VALUES, IMAGE_VERTICAL_ALIGNMENT_VALUES, IMAGE_VERTICAL_RELATIVE_TO_VALUES, IMAGE_WRAP_TEXT_VALUES, LEVEL_SUFFIX_VALUES, LINE_SPACING_RULE_VALUES, NUMBER_FORMAT_VALUES, PARAGRAPH_ALIGNMENT_VALUES, SDT_LOCK_VALUES, SHADING_PATTERN_VALUES, SHAPE_OUTLINE_STYLE_VALUES, SHAPE_TYPE_VALUES, STYLE_TYPE_VALUES, TABLE_CELL_TEXT_DIRECTION_VALUES, TABLE_ROW_HEIGHT_RULE_VALUES, TABLE_WIDTH_TYPE_VALUES, TAB_LEADER_VALUES, TAB_STOP_ALIGNMENT_VALUES, TEXT_EFFECT_VALUES, THEME_COLOR_SLOT_VALUES, UNDERLINE_STYLE_VALUES } from "../types/documentEnumValues.js";
+import * as v from "valibot";
+//#region src/docx/parserEnums.ts
+/**
+* OOXML enum schemas for parser narrowing.
+*
+* Parsers throughout this directory read string-valued XML attributes
+* (`<w:u w:val="single"/>`, `<w:pgBorders w:val="dashed"/>`, …) that
+* the document model types as a small literal union. The historical
+* pattern was `getAttribute(...) as UnderlineStyle`, which lies to
+* the type system: a malformed file produces a typed value that
+* silently contains garbage and breaks downstream consumers.
+*
+* These valibot picklists are the single source of truth for each
+* OOXML enum. `narrowEnum(value, schema)` widens a parsed string to
+* the typed enum *iff* the value is recognised; unknown values
+* become `undefined` so callers can fall back to a default, matching
+* how Word degrades when it doesn't recognise a value.
+*
+* Picklist entries are checked at compile time against the TS union
+* via `satisfies` — a new variant added to the model type fails to
+* compile until the picklist is updated, giving the same compile-time
+* coverage gate as `switch-exhaustiveness-check`.
+*/
+/**
+* Narrow a raw attribute string to a picklist member, or `undefined`
+* if the value isn't recognised. The cast lives once inside the
+* valibot output type; callers receive a properly-typed value with
+* no `as` at the call site.
+*/
+const narrowEnum = (value, schema) => {
+	if (value === null || value === void 0) return;
+	const result = v.safeParse(schema, value);
+	return result.success ? result.output : void 0;
+};
+const ThemeColorSlotSchema = v.picklist(THEME_COLOR_SLOT_VALUES);
+const BorderStyleSchema = v.picklist(BORDER_STYLE_VALUES);
+const UnderlineStyleSchema = v.picklist(UNDERLINE_STYLE_VALUES);
+const HighlightColorSchema = v.picklist(HIGHLIGHT_COLOR_VALUES);
+const TextEffectSchema = v.picklist(TEXT_EFFECT_VALUES);
+const EmphasisMarkSchema = v.picklist(EMPHASIS_MARK_VALUES);
+const FontThemeSchema = v.picklist(FONT_THEME_VALUES);
+const ParagraphAlignmentSchema = v.picklist(PARAGRAPH_ALIGNMENT_VALUES);
+const LineSpacingRuleSchema = v.picklist(LINE_SPACING_RULE_VALUES);
+const TabStopAlignmentSchema = v.picklist(TAB_STOP_ALIGNMENT_VALUES);
+const TabLeaderSchema = v.picklist(TAB_LEADER_VALUES);
+const FrameXAlignSchema = v.picklist(FRAME_X_ALIGN_VALUES);
+const FrameYAlignSchema = v.picklist(FRAME_Y_ALIGN_VALUES);
+const FrameWrapSchema = v.picklist(FRAME_WRAP_VALUES);
+const SdtLockSchema = v.picklist(SDT_LOCK_VALUES);
+const FieldTypeSchema = v.picklist(FIELD_TYPE_VALUES);
+const StyleTypeSchema = v.picklist(STYLE_TYPE_VALUES);
+const ConditionalStyleTypeSchema = v.picklist(CONDITIONAL_STYLE_TYPE_VALUES);
+const TableWidthTypeSchema = v.picklist(TABLE_WIDTH_TYPE_VALUES);
+const TableRowHeightRuleSchema = v.picklist(TABLE_ROW_HEIGHT_RULE_VALUES);
+const TableCellTextDirectionSchema = v.picklist(TABLE_CELL_TEXT_DIRECTION_VALUES);
+const ShadingPatternSchema = v.picklist(SHADING_PATTERN_VALUES);
+const FloatingTableXSpecSchema = v.picklist(FLOATING_TABLE_X_SPEC_VALUES);
+const FloatingTableYSpecSchema = v.picklist(FLOATING_TABLE_Y_SPEC_VALUES);
+const ImageHorizontalRelativeToSchema = v.picklist(IMAGE_HORIZONTAL_RELATIVE_TO_VALUES);
+const ImageHorizontalAlignmentSchema = v.picklist(IMAGE_HORIZONTAL_ALIGNMENT_VALUES);
+const ImageVerticalRelativeToSchema = v.picklist(IMAGE_VERTICAL_RELATIVE_TO_VALUES);
+const ImageVerticalAlignmentSchema = v.picklist(IMAGE_VERTICAL_ALIGNMENT_VALUES);
+const ImageWrapTextSchema = v.picklist(IMAGE_WRAP_TEXT_VALUES);
+const ShapeOutlineStyleSchema = v.picklist(SHAPE_OUTLINE_STYLE_VALUES);
+const ShapeTypeSchema = v.picklist(SHAPE_TYPE_VALUES);
+const NumberFormatSchema = v.picklist(NUMBER_FORMAT_VALUES);
+const LevelSuffixSchema = v.picklist(LEVEL_SUFFIX_VALUES);
+//#endregion
+export { BorderStyleSchema, ConditionalStyleTypeSchema, EmphasisMarkSchema, FieldTypeSchema, FloatingTableXSpecSchema, FloatingTableYSpecSchema, FontThemeSchema, FrameWrapSchema, FrameXAlignSchema, FrameYAlignSchema, HighlightColorSchema, ImageHorizontalAlignmentSchema, ImageHorizontalRelativeToSchema, ImageVerticalAlignmentSchema, ImageVerticalRelativeToSchema, ImageWrapTextSchema, LevelSuffixSchema, LineSpacingRuleSchema, NumberFormatSchema, ParagraphAlignmentSchema, SdtLockSchema, ShadingPatternSchema, ShapeOutlineStyleSchema, ShapeTypeSchema, StyleTypeSchema, TabLeaderSchema, TabStopAlignmentSchema, TableCellTextDirectionSchema, TableRowHeightRuleSchema, TableWidthTypeSchema, TextEffectSchema, ThemeColorSlotSchema, UnderlineStyleSchema, narrowEnum };

package/dist/docx/relsParser.d.ts

@@ -0,0 +1,160 @@
+import { document_d_exports } from "../types/document.js";
+//#region src/docx/relsParser.d.ts
+/**
+ * Relationship type constants for common types
+ */
+declare const RELATIONSHIP_TYPES: {
+  readonly image: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image";
+  readonly hyperlink: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink";
+  readonly header: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/header";
+  readonly footer: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footer";
+  readonly footnotes: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footnotes";
+  readonly endnotes: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/endnotes";
+  readonly styles: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles";
+  readonly numbering: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering";
+  readonly fontTable: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/fontTable";
+  readonly theme: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme";
+  readonly settings: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/settings";
+  readonly webSettings: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/webSettings";
+  readonly oleObject: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/oleObject";
+  readonly chart: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/chart";
+  readonly diagramData: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/diagramData";
+  readonly officeDocument: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument";
+  readonly coreProperties: "http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties";
+  readonly extendedProperties: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/extended-properties";
+  readonly customProperties: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/custom-properties";
+  readonly customXml: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/customXml";
+  readonly comments: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments";
+  readonly commentsExtended: "http://schemas.microsoft.com/office/2011/relationships/commentsExtended";
+};
+/**
+ * Parse a .rels XML file into a RelationshipMap
+ *
+ * @param relsXml - XML content of a .rels file
+ * @returns Map of relationship ID to Relationship object
+ */
+declare function parseRelationships(relsXml: string): document_d_exports.RelationshipMap;
+/**
+ * Get the short type name from a full relationship type URI
+ *
+ * @param typeUri - Full relationship type URI
+ * @returns Short type name (e.g., "image", "hyperlink") or "unknown"
+ */
+declare function getRelationshipTypeName(typeUri: string): string;
+/**
+ * Check if a relationship type is an external link (hyperlink)
+ *
+ * @param rel - Relationship to check
+ * @returns true if this is an external hyperlink
+ */
+declare function isExternalHyperlink(rel: document_d_exports.Relationship): boolean;
+/**
+ * Check if a relationship type is an image
+ *
+ * @param rel - Relationship to check
+ * @returns true if this is an image relationship
+ */
+declare function isImageRelationship(rel: document_d_exports.Relationship): boolean;
+/**
+ * Check if a relationship type is a header
+ *
+ * @param rel - Relationship to check
+ * @returns true if this is a header relationship
+ */
+declare function isHeaderRelationship(rel: document_d_exports.Relationship): boolean;
+/**
+ * Check if a relationship type is a footer
+ *
+ * @param rel - Relationship to check
+ * @returns true if this is a footer relationship
+ */
+declare function isFooterRelationship(rel: document_d_exports.Relationship): boolean;
+/**
+ * Filter relationships by type
+ *
+ * @param map - RelationshipMap to filter
+ * @param type - Relationship type URI to filter by
+ * @returns Array of matching relationships
+ */
+declare function filterByType(map: document_d_exports.RelationshipMap, type: document_d_exports.RelationshipType): document_d_exports.Relationship[];
+/**
+ * Get all images from a relationship map
+ *
+ * @param map - RelationshipMap to search
+ * @returns Array of image relationships
+ */
+declare function getImages(map: document_d_exports.RelationshipMap): document_d_exports.Relationship[];
+/**
+ * Get all hyperlinks from a relationship map
+ *
+ * @param map - RelationshipMap to search
+ * @returns Array of hyperlink relationships
+ */
+declare function getHyperlinks(map: document_d_exports.RelationshipMap): document_d_exports.Relationship[];
+/**
+ * Get all headers from a relationship map
+ *
+ * @param map - RelationshipMap to search
+ * @returns Array of header relationships
+ */
+declare function getHeaders(map: document_d_exports.RelationshipMap): document_d_exports.Relationship[];
+/**
+ * Get all footers from a relationship map
+ *
+ * @param map - RelationshipMap to search
+ * @returns Array of footer relationships
+ */
+declare function getFooters(map: document_d_exports.RelationshipMap): document_d_exports.Relationship[];
+/**
+ * Resolve a relationship ID to a target path
+ *
+ * @param map - RelationshipMap to search
+ * @param rId - Relationship ID (e.g., "rId1")
+ * @returns Target path or undefined if not found
+ */
+declare function resolveTarget(map: document_d_exports.RelationshipMap, rId: string): string | undefined;
+/**
+ * Resolve a relationship ID to a full relationship
+ *
+ * @param map - RelationshipMap to search
+ * @param rId - Relationship ID (e.g., "rId1")
+ * @returns Relationship or undefined if not found
+ */
+declare function resolveRelationship(map: document_d_exports.RelationshipMap, rId: string): document_d_exports.Relationship | undefined;
+/**
+ * Resolve a relative target path to an absolute path within the DOCX
+ *
+ * For example, if basePath is "word/_rels/document.xml.rels" and
+ * target is "media/image1.png", the result is "word/media/image1.png"
+ *
+ * @param basePath - Path of the .rels file
+ * @param target - Relative target from the relationship
+ * @returns Absolute path within the DOCX
+ */
+declare function resolveRelativePath(basePath: string, target: string): string;
+/**
+ * Parse document.xml.rels specifically
+ *
+ * This is a convenience wrapper for the main document relationships.
+ *
+ * @param relsXml - XML content of word/_rels/document.xml.rels
+ * @returns RelationshipMap
+ */
+declare function parseDocumentRelationships(relsXml: string): document_d_exports.RelationshipMap;
+/**
+ * Parse package-level .rels
+ *
+ * This is a convenience wrapper for the package relationships (_rels/.rels)
+ *
+ * @param relsXml - XML content of _rels/.rels
+ * @returns RelationshipMap
+ */
+declare function parsePackageRelationships(relsXml: string): document_d_exports.RelationshipMap;
+/**
+ * Debug: Print all relationships in a map
+ *
+ * @param map - RelationshipMap to print
+ */
+declare function formatRelationships(map: document_d_exports.RelationshipMap): string;
+//#endregion
+export { RELATIONSHIP_TYPES, filterByType, formatRelationships, getFooters, getHeaders, getHyperlinks, getImages, getRelationshipTypeName, isExternalHyperlink, isFooterRelationship, isHeaderRelationship, isImageRelationship, parseDocumentRelationships, parsePackageRelationships, parseRelationships, resolveRelationship, resolveRelativePath, resolveTarget };

package/dist/docx/relsParser.js

@@ -0,0 +1,235 @@
+import { getAttribute, getChildElements, parseXmlDocument } from "./xmlParser.js";
+//#region src/docx/relsParser.ts
+/**
+* Relationship type constants for common types
+*/
+const RELATIONSHIP_TYPES = {
+	image: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image",
+	hyperlink: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink",
+	header: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/header",
+	footer: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footer",
+	footnotes: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footnotes",
+	endnotes: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/endnotes",
+	styles: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles",
+	numbering: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering",
+	fontTable: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/fontTable",
+	theme: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme",
+	settings: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/settings",
+	webSettings: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/webSettings",
+	oleObject: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/oleObject",
+	chart: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/chart",
+	diagramData: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/diagramData",
+	officeDocument: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument",
+	coreProperties: "http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties",
+	extendedProperties: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/extended-properties",
+	customProperties: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/custom-properties",
+	customXml: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/customXml",
+	comments: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments",
+	commentsExtended: "http://schemas.microsoft.com/office/2011/relationships/commentsExtended"
+};
+/**
+* Parse a .rels XML file into a RelationshipMap
+*
+* @param relsXml - XML content of a .rels file
+* @returns Map of relationship ID to Relationship object
+*/
+function parseRelationships(relsXml) {
+	const map = /* @__PURE__ */ new Map();
+	if (!relsXml || relsXml.trim().length === 0) return map;
+	const root = parseXmlDocument(relsXml);
+	if (!root) return map;
+	const children = getChildElements(root);
+	for (const child of children) {
+		const name = child.name || "";
+		if (!name.endsWith("Relationship") && !name.includes(":Relationship")) continue;
+		const id = getAttribute(child, null, "Id");
+		const type = getAttribute(child, null, "Type");
+		const target = getAttribute(child, null, "Target");
+		const targetMode = getAttribute(child, null, "TargetMode");
+		if (!id || !type || !target) continue;
+		const relationship = {
+			id,
+			type,
+			target
+		};
+		if (targetMode === "External") relationship.targetMode = "External";
+		else if (targetMode === "Internal") relationship.targetMode = "Internal";
+		map.set(id, relationship);
+	}
+	return map;
+}
+/**
+* Get the short type name from a full relationship type URI
+*
+* @param typeUri - Full relationship type URI
+* @returns Short type name (e.g., "image", "hyperlink") or "unknown"
+*/
+function getRelationshipTypeName(typeUri) {
+	for (const [name, uri] of Object.entries(RELATIONSHIP_TYPES)) if (uri === typeUri) return name;
+	const lastSlash = typeUri.lastIndexOf("/");
+	if (lastSlash !== -1) return typeUri.slice(lastSlash + 1);
+	return "unknown";
+}
+/**
+* Check if a relationship type is an external link (hyperlink)
+*
+* @param rel - Relationship to check
+* @returns true if this is an external hyperlink
+*/
+function isExternalHyperlink(rel) {
+	return rel.type === RELATIONSHIP_TYPES.hyperlink && rel.targetMode === "External";
+}
+/**
+* Check if a relationship type is an image
+*
+* @param rel - Relationship to check
+* @returns true if this is an image relationship
+*/
+function isImageRelationship(rel) {
+	return rel.type === RELATIONSHIP_TYPES.image;
+}
+/**
+* Check if a relationship type is a header
+*
+* @param rel - Relationship to check
+* @returns true if this is a header relationship
+*/
+function isHeaderRelationship(rel) {
+	return rel.type === RELATIONSHIP_TYPES.header;
+}
+/**
+* Check if a relationship type is a footer
+*
+* @param rel - Relationship to check
+* @returns true if this is a footer relationship
+*/
+function isFooterRelationship(rel) {
+	return rel.type === RELATIONSHIP_TYPES.footer;
+}
+/**
+* Filter relationships by type
+*
+* @param map - RelationshipMap to filter
+* @param type - Relationship type URI to filter by
+* @returns Array of matching relationships
+*/
+function filterByType(map, type) {
+	const results = [];
+	for (const rel of map.values()) if (rel.type === type) results.push(rel);
+	return results;
+}
+/**
+* Get all images from a relationship map
+*
+* @param map - RelationshipMap to search
+* @returns Array of image relationships
+*/
+function getImages(map) {
+	return filterByType(map, RELATIONSHIP_TYPES.image);
+}
+/**
+* Get all hyperlinks from a relationship map
+*
+* @param map - RelationshipMap to search
+* @returns Array of hyperlink relationships
+*/
+function getHyperlinks(map) {
+	return filterByType(map, RELATIONSHIP_TYPES.hyperlink);
+}
+/**
+* Get all headers from a relationship map
+*
+* @param map - RelationshipMap to search
+* @returns Array of header relationships
+*/
+function getHeaders(map) {
+	return filterByType(map, RELATIONSHIP_TYPES.header);
+}
+/**
+* Get all footers from a relationship map
+*
+* @param map - RelationshipMap to search
+* @returns Array of footer relationships
+*/
+function getFooters(map) {
+	return filterByType(map, RELATIONSHIP_TYPES.footer);
+}
+/**
+* Resolve a relationship ID to a target path
+*
+* @param map - RelationshipMap to search
+* @param rId - Relationship ID (e.g., "rId1")
+* @returns Target path or undefined if not found
+*/
+function resolveTarget(map, rId) {
+	return map.get(rId)?.target;
+}
+/**
+* Resolve a relationship ID to a full relationship
+*
+* @param map - RelationshipMap to search
+* @param rId - Relationship ID (e.g., "rId1")
+* @returns Relationship or undefined if not found
+*/
+function resolveRelationship(map, rId) {
+	return map.get(rId);
+}
+/**
+* Resolve a relative target path to an absolute path within the DOCX
+*
+* For example, if basePath is "word/_rels/document.xml.rels" and
+* target is "media/image1.png", the result is "word/media/image1.png"
+*
+* @param basePath - Path of the .rels file
+* @param target - Relative target from the relationship
+* @returns Absolute path within the DOCX
+*/
+function resolveRelativePath(basePath, target) {
+	if (target.startsWith("/")) return target.slice(1);
+	const lastSlash = basePath.lastIndexOf("/");
+	let directory = lastSlash !== -1 ? basePath.slice(0, lastSlash) : "";
+	if (directory.endsWith("/_rels")) directory = directory.slice(0, -6);
+	else if (directory === "_rels") directory = "";
+	const parts = target.split("/");
+	const dirParts = directory ? directory.split("/") : [];
+	for (const part of parts) if (part === "..") dirParts.pop();
+	else if (part !== ".") dirParts.push(part);
+	return dirParts.join("/");
+}
+/**
+* Parse document.xml.rels specifically
+*
+* This is a convenience wrapper for the main document relationships.
+*
+* @param relsXml - XML content of word/_rels/document.xml.rels
+* @returns RelationshipMap
+*/
+function parseDocumentRelationships(relsXml) {
+	return parseRelationships(relsXml);
+}
+/**
+* Parse package-level .rels
+*
+* This is a convenience wrapper for the package relationships (_rels/.rels)
+*
+* @param relsXml - XML content of _rels/.rels
+* @returns RelationshipMap
+*/
+function parsePackageRelationships(relsXml) {
+	return parseRelationships(relsXml);
+}
+/**
+* Debug: Print all relationships in a map
+*
+* @param map - RelationshipMap to print
+*/
+function formatRelationships(map) {
+	const lines = ["Relationships:"];
+	for (const [id, rel] of map.entries()) {
+		const typeName = getRelationshipTypeName(rel.type);
+		lines.push(`  ${id}: ${typeName} -> ${rel.target}${rel.targetMode === "External" ? " (External)" : ""}`);
+	}
+	return lines.join("\n");
+}
+//#endregion
+export { RELATIONSHIP_TYPES, filterByType, formatRelationships, getFooters, getHeaders, getHyperlinks, getImages, getRelationshipTypeName, isExternalHyperlink, isFooterRelationship, isHeaderRelationship, isImageRelationship, parseDocumentRelationships, parsePackageRelationships, parseRelationships, resolveRelationship, resolveRelativePath, resolveTarget };

package/dist/docx/replyToComment.d.ts

@@ -0,0 +1,29 @@
+import { document_d_exports } from "../types/document.js";
+
+//#region src/docx/replyToComment.d.ts
+type CreateCommentReplyInput = {
+  author: string;
+  text: string;
+  initials?: string; /** ISO date; defaults to now. */
+  date?: string;
+};
+/**
+ * Build a reply to `parentCommentId` against an existing comment list and
+ * return it, mutating the thread root's last paragraph to guarantee it has a
+ * paraId. Does NOT append the reply to `comments` — the caller owns storage
+ * (the standalone {@link replyToComment} writes it back to the document model;
+ * the headless reviewer keeps its own created-comment list). Returns `null` when
+ * the parent comment does not exist, or is malformed (no paragraphs) so it
+ * cannot anchor a thread. A reply to a reply re-parents onto the same thread as
+ * the target (Word threads are flat: every reply links to the root).
+ */
+declare const createReply: (comments: readonly document_d_exports.Comment[], parentCommentId: number, input: CreateCommentReplyInput) => document_d_exports.Comment | null;
+/**
+ * Append a reply to `parentCommentId` in `doc`'s comment list, mutating the
+ * document model in place, and return the created reply. Returns `null` when the
+ * parent comment does not exist or cannot anchor a thread (see
+ * {@link createReply}).
+ */
+declare const replyToComment: (doc: document_d_exports.Document, parentCommentId: number, input: CreateCommentReplyInput) => document_d_exports.Comment | null;
+//#endregion
+export { CreateCommentReplyInput, createReply, replyToComment };

package/dist/docx/replyToComment.js

@@ -0,0 +1,73 @@
+import { generateHexId } from "../utils/hexId.js";
+//#region src/docx/replyToComment.ts
+const nextCommentId = (comments) => {
+	let max = 0;
+	for (const comment of comments) if (comment.id > max) max = comment.id;
+	return max + 1;
+};
+const usedParaIds = (comments) => {
+	const ids = /* @__PURE__ */ new Set();
+	for (const comment of comments) for (const paragraph of comment.content) if (paragraph.paraId) ids.add(paragraph.paraId.toUpperCase());
+	return ids;
+};
+const freshParaId = (used) => {
+	let id = generateHexId();
+	while (used.has(id.toUpperCase())) id = generateHexId();
+	used.add(id.toUpperCase());
+	return id;
+};
+/**
+* Build a reply to `parentCommentId` against an existing comment list and
+* return it, mutating the thread root's last paragraph to guarantee it has a
+* paraId. Does NOT append the reply to `comments` — the caller owns storage
+* (the standalone {@link replyToComment} writes it back to the document model;
+* the headless reviewer keeps its own created-comment list). Returns `null` when
+* the parent comment does not exist, or is malformed (no paragraphs) so it
+* cannot anchor a thread. A reply to a reply re-parents onto the same thread as
+* the target (Word threads are flat: every reply links to the root).
+*/
+const createReply = (comments, parentCommentId, input) => {
+	const parent = comments.find((comment) => comment.id === parentCommentId);
+	if (!parent) return null;
+	const threadRootId = parent.parentId ?? parent.id;
+	const rootLastParagraph = ((comments.find((comment) => comment.id === threadRootId) ?? parent).content ?? []).at(-1);
+	if (!rootLastParagraph) return null;
+	const used = usedParaIds(comments);
+	if (!rootLastParagraph.paraId) rootLastParagraph.paraId = freshParaId(used);
+	const replyParagraph = {
+		type: "paragraph",
+		formatting: {},
+		paraId: freshParaId(used),
+		content: [{
+			type: "run",
+			formatting: {},
+			content: [{
+				type: "text",
+				text: input.text
+			}]
+		}]
+	};
+	return {
+		id: nextCommentId(comments),
+		author: input.author,
+		date: input.date ?? (/* @__PURE__ */ new Date()).toISOString(),
+		parentId: threadRootId,
+		content: [replyParagraph],
+		...input.initials !== void 0 ? { initials: input.initials } : {}
+	};
+};
+/**
+* Append a reply to `parentCommentId` in `doc`'s comment list, mutating the
+* document model in place, and return the created reply. Returns `null` when the
+* parent comment does not exist or cannot anchor a thread (see
+* {@link createReply}).
+*/
+const replyToComment = (doc, parentCommentId, input) => {
+	const comments = doc.package.document.comments ?? [];
+	const reply = createReply(comments, parentCommentId, input);
+	if (!reply) return null;
+	doc.package.document.comments = [...comments, reply];
+	return reply;
+};
+//#endregion
+export { createReply, replyToComment };