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

package/dist/managers/editorShortcuts.d.ts

@@ -0,0 +1,42 @@
+import { EditorState, Transaction } from "prosemirror-state";
+
+//#region src/managers/editorShortcuts.d.ts
+declare function isMacPlatform(): boolean;
+/**
+ * `target` is an input-like element that the user is typing into. We must
+ * not intercept Delete/Backspace there — only when focus is in the editor
+ * surface (or nowhere at all).
+ */
+declare function isFocusInInputLike(target: EventTarget | null, editorDom: HTMLElement | null | undefined): boolean;
+/** The editor action a keydown maps to, or `none` when it is not a shortcut. */
+type EditorKeydownIntent = {
+  type: "deleteSelectedTable";
+} | {
+  type: "openFind";
+} | {
+  type: "print";
+} | {
+  type: "none";
+};
+type ClassifyEditorKeydownOptions = {
+  /** Whether the platform uses Cmd (Mac) rather than Ctrl as the primary modifier. */isMac: boolean; /** Whether focus is in a non-editor input/textarea/contenteditable. */
+  isInputLike: boolean;
+};
+/**
+ * Map a keydown to an editor intent:
+ *  - Cmd/Ctrl+F or Cmd/Ctrl+H → open find
+ *  - Cmd/Ctrl+P (no auto-repeat) → custom print
+ *  - Delete/Backspace (no modifiers, focus not in an input) → delete selected table
+ */
+declare function classifyEditorKeydown(e: KeyboardEvent, {
+  isMac,
+  isInputLike
+}: ClassifyEditorKeydownOptions): EditorKeydownIntent;
+/**
+ * If the selection is a ProseMirror `CellSelection` covering every cell of its
+ * table, delete the table and return `true`. Returns `false` for any other
+ * selection so the caller can fall back to a layout-overlay table selection.
+ */
+declare function deleteSelectedTable(state: EditorState, dispatch: (tr: Transaction) => void): boolean;
+//#endregion
+export { ClassifyEditorKeydownOptions, EditorKeydownIntent, classifyEditorKeydown, deleteSelectedTable, isFocusInInputLike, isMacPlatform };

package/dist/managers/editorShortcuts.js

@@ -0,0 +1,60 @@
+import { getTableContext } from "../prosemirror/extensions/nodes/TableExtension.js";
+import { deleteTable } from "../prosemirror/commands/table.js";
+//#region src/managers/editorShortcuts.ts
+function isMacPlatform() {
+	if (typeof navigator === "undefined") return false;
+	return /Mac|iPod|iPhone|iPad/u.test(navigator.platform);
+}
+/**
+* `target` is an input-like element that the user is typing into. We must
+* not intercept Delete/Backspace there — only when focus is in the editor
+* surface (or nowhere at all).
+*/
+function isFocusInInputLike(target, editorDom) {
+	if (!(target instanceof HTMLElement)) return false;
+	if (target.tagName === "INPUT" || target.tagName === "TEXTAREA") return true;
+	if (target.isContentEditable && target !== editorDom) return true;
+	return false;
+}
+/**
+* Map a keydown to an editor intent:
+*  - Cmd/Ctrl+F or Cmd/Ctrl+H → open find
+*  - Cmd/Ctrl+P (no auto-repeat) → custom print
+*  - Delete/Backspace (no modifiers, focus not in an input) → delete selected table
+*/
+function classifyEditorKeydown(e, { isMac, isInputLike }) {
+	const cmdOrCtrl = isMac ? e.metaKey : e.ctrlKey;
+	if (!cmdOrCtrl && !e.shiftKey && !e.altKey && (e.key === "Delete" || e.key === "Backspace") && !isInputLike) return { type: "deleteSelectedTable" };
+	if (cmdOrCtrl && !e.shiftKey && !e.altKey) {
+		const key = e.key.toLowerCase();
+		if (key === "f" || key === "h") return { type: "openFind" };
+		if (key === "p" && !e.repeat) return { type: "print" };
+	}
+	return { type: "none" };
+}
+/**
+* If the selection is a ProseMirror `CellSelection` covering every cell of its
+* table, delete the table and return `true`. Returns `false` for any other
+* selection so the caller can fall back to a layout-overlay table selection.
+*/
+function deleteSelectedTable(state, dispatch) {
+	const sel = state.selection;
+	if (!("$anchorCell" in sel && typeof sel.forEachCell === "function")) return false;
+	const context = getTableContext(state);
+	if (!(context.isInTable && context.table)) return false;
+	let totalCells = 0;
+	context.table.descendants((node) => {
+		if (node.type.name === "tableCell" || node.type.name === "tableHeader") totalCells += 1;
+	});
+	let selectedCells = 0;
+	sel.forEachCell(() => {
+		selectedCells += 1;
+	});
+	if (totalCells > 0 && selectedCells >= totalCells) {
+		deleteTable(state, dispatch);
+		return true;
+	}
+	return false;
+}
+//#endregion
+export { classifyEditorKeydown, deleteSelectedTable, isFocusInInputLike, isMacPlatform };

package/dist/managers/types.d.ts

@@ -0,0 +1,41 @@
+//#region src/managers/types.d.ts
+/** Cell coordinates in a table */
+type CellCoordinates = {
+  tableIndex: number;
+  rowIndex: number;
+  columnIndex: number;
+};
+/** Viewport anchor (px) where the context menu opens. */
+type ContextMenuAnchor = {
+  x: number;
+  y: number;
+};
+/** ContextMenuManager snapshot. */
+type ContextMenuSnapshot = {
+  isOpen: boolean;
+  position: ContextMenuAnchor;
+  hasSelection: boolean;
+  selectionRange: {
+    from: number;
+    to: number;
+  };
+  cursorInTable: boolean;
+  cursorInTrackedChange: boolean;
+};
+/** Error severity levels */
+type ErrorSeverity = "error" | "warning" | "info";
+/** Error notification */
+type ErrorNotification = {
+  id: string;
+  message: string;
+  severity: ErrorSeverity;
+  details?: string;
+  timestamp: number;
+  dismissed?: boolean;
+};
+/** ErrorManager snapshot */
+type ErrorManagerSnapshot = {
+  notifications: ErrorNotification[];
+};
+//#endregion
+export { CellCoordinates, ContextMenuAnchor, ContextMenuSnapshot, ErrorManagerSnapshot, ErrorNotification, ErrorSeverity };

package/dist/markdown/annotations.d.ts

@@ -0,0 +1,14 @@
+import { document_d_exports } from "../types/document.js";
+import { RenderContext } from "./types.js";
+
+//#region src/markdown/annotations.d.ts
+declare function wrapInsertion(ctx: RenderContext, info: document_d_exports.TrackedChangeInfo, inner: string): string;
+declare function wrapDeletion(ctx: RenderContext, info: document_d_exports.TrackedChangeInfo, inner: string): string;
+declare function wrapMoveFrom(ctx: RenderContext, info: document_d_exports.TrackedChangeInfo, inner: string): string;
+declare function wrapMoveTo(ctx: RenderContext, info: document_d_exports.TrackedChangeInfo, inner: string): string;
+declare function wrapComment(ctx: RenderContext, meta: {
+  id: number;
+  author?: string;
+}, inner: string): string;
+//#endregion
+export { wrapComment, wrapDeletion, wrapInsertion, wrapMoveFrom, wrapMoveTo };

package/dist/markdown/annotations.js

@@ -0,0 +1,42 @@
+//#region src/markdown/annotations.ts
+function escapeAttr(value) {
+	return value.replace(/&/gu, "&amp;").replace(/</gu, "&lt;").replace(/>/gu, "&gt;").replace(/"/gu, "&quot;");
+}
+function attrString(info) {
+	const parts = [];
+	if (info.author) parts.push(`author="${escapeAttr(info.author)}"`);
+	if (info.date) parts.push(`date="${escapeAttr(info.date)}"`);
+	if (typeof info.id === "number") parts.push(`id="${info.id}"`);
+	return parts.length ? ` ${parts.join(" ")}` : "";
+}
+/**
+* Wrap `inner` with the active annotations mode's encoding.
+*
+* `keepWhenStripped` controls what to emit when `annotations === "strip"`:
+* insertions and comments keep the visible text; deletions drop entirely.
+*/
+function wrap(ctx, inner, htmlTag, pandocClass, info, extraHtmlAttrs, mode, keepWhenStripped) {
+	if (ctx.opts.annotations === "strip") return keepWhenStripped ? inner : "";
+	if (ctx.opts.annotations === "pandoc") {
+		const author = info.author ? ` author="${escapeAttr(info.author)}"` : "";
+		return `[${inner}]{.${pandocClass}${mode === "comment" && typeof info.id === "number" ? ` id="${info.id}"` : ""}${author}}`;
+	}
+	return `<${htmlTag}${attrString(info)}${extraHtmlAttrs}>${inner}</${htmlTag}>`;
+}
+function wrapInsertion(ctx, info, inner) {
+	return wrap(ctx, inner, "ins", "ins", info, "", "tracked", true);
+}
+function wrapDeletion(ctx, info, inner) {
+	return wrap(ctx, inner, "del", "del", info, "", "tracked", false);
+}
+function wrapMoveFrom(ctx, info, inner) {
+	return wrap(ctx, inner, "del", "move-from", info, " data-move=\"from\"", "tracked", false);
+}
+function wrapMoveTo(ctx, info, inner) {
+	return wrap(ctx, inner, "ins", "move-to", info, " data-move=\"to\"", "tracked", true);
+}
+function wrapComment(ctx, meta, inner) {
+	return wrap(ctx, inner, "comment", "comment", meta, "", "comment", true);
+}
+//#endregion
+export { wrapComment, wrapDeletion, wrapInsertion, wrapMoveFrom, wrapMoveTo };

package/dist/markdown/escape.d.ts

@@ -0,0 +1,36 @@
+//#region src/markdown/escape.d.ts
+/**
+ * Markdown escaping. Only characters that would change the parsed structure
+ * get escaped. Context-sensitive: pipes only matter inside table cells.
+ *
+ * Ported from eigenpal/docx-editor PR #595 (`@eigenpal/docx-editor-core/markdown`).
+ */
+/**
+ * Escape only characters that would change markdown structure mid-text:
+ *   - backslash, backtick, asterisk, brackets (always)
+ *   - underscore: only at word boundaries (emphasis trigger)
+ *   - angle brackets: only when they look like a tag/autolink
+ *
+ * Characters like `.` `-` `+` `#` `(` `)` `!` are only meaningful at line
+ * starts or in specific adjacency; we let the block-level renderer decide
+ * when to escape those.
+ */
+declare function escapeInline(text: string): string;
+/**
+ * Cells use `|` as the column separator. The input is already markdown (each
+ * cell is a rendered paragraph that ran through {@link escapeInline}), so a
+ * backslash escape would interact with existing escape sequences — encode the
+ * pipe as the HTML entity instead, which GFM renders as a literal `|` without
+ * treating it as a delimiter. Newlines become `<br>` to keep the row on one
+ * line.
+ */
+declare function escapeTableCell(text: string): string;
+declare function escapeLinkUrl(url: string): string;
+/**
+ * Alt text inside `![alt](url)`. Raw (un-escaped) text, so escape the backslash
+ * first, then the brackets that would confuse the link parser, and collapse
+ * newlines so the alt stays single-line.
+ */
+declare function escapeAltText(text: string): string;
+//#endregion
+export { escapeAltText, escapeInline, escapeLinkUrl, escapeTableCell };

package/dist/markdown/escape.js

@@ -0,0 +1,59 @@
+//#region src/markdown/escape.ts
+/**
+* Markdown escaping. Only characters that would change the parsed structure
+* get escaped. Context-sensitive: pipes only matter inside table cells.
+*
+* Ported from eigenpal/docx-editor PR #595 (`@eigenpal/docx-editor-core/markdown`).
+*/
+/**
+* Escape only characters that would change markdown structure mid-text:
+*   - backslash, backtick, asterisk, brackets (always)
+*   - underscore: only at word boundaries (emphasis trigger)
+*   - angle brackets: only when they look like a tag/autolink
+*
+* Characters like `.` `-` `+` `#` `(` `)` `!` are only meaningful at line
+* starts or in specific adjacency; we let the block-level renderer decide
+* when to escape those.
+*/
+function escapeInline(text) {
+	let out = text.replace(/(?<ch>[\\`*[\]])/gu, "\\$<ch>");
+	out = out.replace(/(?<pre>^|\s)_/gu, "$<pre>\\_");
+	out = out.replace(/_(?<post>\s|$)/gu, "\\_$<post>");
+	out = out.replace(/<(?<tag>\/?[A-Za-z][\w-]*)(?=[\s/>])/gu, "\\<$<tag>");
+	return out;
+}
+/**
+* Cells use `|` as the column separator. The input is already markdown (each
+* cell is a rendered paragraph that ran through {@link escapeInline}), so a
+* backslash escape would interact with existing escape sequences — encode the
+* pipe as the HTML entity instead, which GFM renders as a literal `|` without
+* treating it as a delimiter. Newlines become `<br>` to keep the row on one
+* line.
+*/
+function escapeTableCell(text) {
+	return text.replace(/\|/gu, "&#124;").replace(/\r?\n/gu, "<br>");
+}
+/**
+* Hyperlink URLs in inline form need parens balanced; we URL-encode the
+* problematic characters rather than escape, so the link still resolves.
+* `encodeURIComponent` leaves `(` and `)` untouched, so an unbalanced paren in
+* a DOCX URL (e.g. `https://example.com/a)b`) would close the inline
+* `[text](url)` destination early; encode the parens explicitly.
+*/
+const LINK_URL_ENCODED = {
+	"(": "%28",
+	")": "%29"
+};
+function escapeLinkUrl(url) {
+	return url.replace(/[()<>"\s]/gu, (ch) => LINK_URL_ENCODED[ch] ?? encodeURIComponent(ch));
+}
+/**
+* Alt text inside `![alt](url)`. Raw (un-escaped) text, so escape the backslash
+* first, then the brackets that would confuse the link parser, and collapse
+* newlines so the alt stays single-line.
+*/
+function escapeAltText(text) {
+	return text.replace(/(?<ch>[\\[\]])/gu, "\\$<ch>").replace(/\r?\n/gu, " ");
+}
+//#endregion
+export { escapeAltText, escapeInline, escapeLinkUrl, escapeTableCell };

package/dist/markdown/fromMarkdown.d.ts

@@ -0,0 +1,11 @@
+import { document_d_exports } from "../types/document.js";
+
+//#region src/markdown/fromMarkdown.d.ts
+/**
+ * Convert a markdown string to a parsed `Document`. Synchronous. The result is
+ * ready to hand to the editor (`<DocxEditor document={…} />`) and to re-export
+ * via {@link toMarkdown}.
+ */
+declare function fromMarkdown(markdown: string): document_d_exports.Document;
+//#endregion
+export { fromMarkdown };

package/dist/markdown/fromMarkdown.js

@@ -0,0 +1,223 @@
+import { createEmptyDocument } from "../utils/createDocument.js";
+import { sanitizeExternalUrl } from "../utils/urlSecurity.js";
+import { marked } from "marked";
+//#region src/markdown/fromMarkdown.ts
+/**
+* Markdown → DOCX-document import — the inverse of {@link toMarkdown} and the
+* second half of the skills bridge. Parses the GFM subset skill bodies use
+* (headings, paragraphs, bold/italic/strike, inline code, bullet + ordered
+* lists incl. nesting, pipe tables, blockquotes, links) into the docx
+* `Document` model so a skill's markdown can be edited in the Folio editor and
+* re-exported with {@link toMarkdown} without drift.
+*
+* Round-trip notes:
+* - Lists are emitted as real list paragraphs (`listRendering`), so the editor
+*   shows a marker and {@link toMarkdown} re-derives `- ` / `1. ` rather than
+*   leaking a literal bullet glyph into the text.
+* - Inline code uses `Courier New` — a whitelisted monospace family that
+*   {@link toMarkdown} infers back to a backtick span (Folio renders it via its
+*   bundled Cousine substitute).
+* - Markdown carries no page geometry, so the section is flattened to a
+*   continuous, header/footer-free band (a skill body is a document, not a
+*   Word page). Headers/footers live outside `document.content` and are never
+*   produced here.
+*/
+const MONO_FONT = {
+	ascii: "Courier New",
+	hAnsi: "Courier New"
+};
+const isTokenType = (token, type) => token.type === type;
+const textRun = (text, fmt = {}) => {
+	const formatting = {
+		...fmt.bold ? { bold: true } : {},
+		...fmt.italic ? { italic: true } : {},
+		...fmt.strike ? { strike: true } : {},
+		...fmt.mono ? { fontFamily: MONO_FONT } : {}
+	};
+	const segments = text.split("\n");
+	const content = [];
+	for (const [index, segment] of segments.entries()) {
+		if (index > 0) content.push({ type: "break" });
+		if (segment.length > 0) content.push({
+			type: "text",
+			text: segment
+		});
+	}
+	if (content.length === 0) content.push({
+		type: "text",
+		text: ""
+	});
+	return {
+		type: "run",
+		formatting,
+		content
+	};
+};
+const sanitizeMarkdownHref = (rawHref) => {
+	const trimmed = rawHref.trim();
+	if (!trimmed) return;
+	if (trimmed.startsWith("#")) {
+		const anchor = trimmed.slice(1);
+		if (!anchor || hasUnsafeAnchorCharacter(anchor)) return;
+		return `#${anchor}`;
+	}
+	return sanitizeExternalUrl(trimmed);
+};
+const hasUnsafeAnchorCharacter = (anchor) => {
+	for (const char of anchor) {
+		const codePoint = char.codePointAt(0) ?? 0;
+		if (codePoint <= 32 || codePoint === 127 || char.trim() === "") return true;
+	}
+	return false;
+};
+const inlineToRuns = (tokens, fallback, base) => {
+	if (!tokens || tokens.length === 0) return [textRun(fallback, base)];
+	const runs = [];
+	for (const token of tokens) if (isTokenType(token, "strong")) runs.push(...inlineToRuns(token.tokens, token.text, {
+		...base,
+		bold: true
+	}));
+	else if (isTokenType(token, "em")) runs.push(...inlineToRuns(token.tokens, token.text, {
+		...base,
+		italic: true
+	}));
+	else if (isTokenType(token, "del")) runs.push(...inlineToRuns(token.tokens, token.text, {
+		...base,
+		strike: true
+	}));
+	else if (isTokenType(token, "codespan")) runs.push(textRun(token.text, {
+		...base,
+		mono: true
+	}));
+	else if (isTokenType(token, "link")) {
+		const children = inlineToRuns(token.tokens, token.text, base).filter((child) => child.type === "run");
+		const href = sanitizeMarkdownHref(token.href);
+		const linkChildren = children.length > 0 ? children : [textRun(token.text, base)];
+		if (!href) {
+			runs.push(...linkChildren);
+			continue;
+		}
+		const anchor = href.startsWith("#") ? href.slice(1) : void 0;
+		runs.push({
+			type: "hyperlink",
+			href,
+			...anchor ? { anchor } : {},
+			children: linkChildren
+		});
+	} else if (isTokenType(token, "paragraph")) runs.push(...inlineToRuns(token.tokens, token.text, base));
+	else if (token.type === "br") runs.push({
+		type: "run",
+		content: [{ type: "break" }]
+	});
+	else if (token.type === "space") {
+		if (runs.length > 0 && token.raw.includes("\n")) runs.push(textRun("\n", base));
+	} else if (isTokenType(token, "text")) {
+		const nested = token.tokens;
+		if (nested && nested.length > 0) runs.push(...inlineToRuns(nested, token.text, base));
+		else runs.push(textRun(token.text, base));
+	} else if ("text" in token && typeof token.text === "string") runs.push(textRun(token.text, base));
+	return runs.length > 0 ? runs : [textRun(fallback, base)];
+};
+const para = (runs, styleId) => ({
+	type: "paragraph",
+	formatting: styleId ? { styleId } : {},
+	content: runs.length > 0 ? runs : [textRun("")]
+});
+const listPara = (runs, rendering) => ({
+	type: "paragraph",
+	formatting: { numPr: {
+		numId: rendering.numId,
+		ilvl: rendering.level
+	} },
+	listRendering: rendering,
+	content: runs.length > 0 ? runs : [textRun("")]
+});
+const cellOf = (cell) => ({
+	type: "tableCell",
+	content: [para(inlineToRuns(cell.tokens, cell.text, {}))]
+});
+const tableFromToken = (token) => ({
+	type: "table",
+	rows: [{
+		type: "tableRow",
+		cells: token.header.map((c) => cellOf(c))
+	}, ...token.rows.map((row) => ({
+		type: "tableRow",
+		cells: row.map((c) => cellOf(c))
+	}))]
+});
+const listBlocks = (list, level, numId) => {
+	const out = [];
+	const start = Number(list.start) || 1;
+	const decimalLevels = Array.from({ length: level + 1 }, () => "decimal");
+	for (const item of list.items) {
+		const rendering = list.ordered ? {
+			marker: `%${level + 1}.`,
+			level,
+			numId,
+			isBullet: false,
+			numFmt: "decimal",
+			levelNumFmts: decimalLevels,
+			...start !== 1 && { startOverride: start }
+		} : {
+			marker: "•",
+			level,
+			numId,
+			isBullet: true
+		};
+		const inlineTokens = [];
+		const nestedLists = [];
+		for (const child of item.tokens) if (isTokenType(child, "list")) nestedLists.push(child);
+		else inlineTokens.push(child);
+		out.push(listPara(inlineToRuns(inlineTokens, item.text, {}), rendering));
+		for (const nested of nestedLists) out.push(...listBlocks(nested, level + 1, numId));
+	}
+	return out;
+};
+const blocksFromTokens = (tokens, numIds) => {
+	const blocks = [];
+	for (const token of tokens ?? []) if (isTokenType(token, "heading")) {
+		const level = Math.min(Math.max(token.depth, 1), 4);
+		blocks.push(para(inlineToRuns(token.tokens, token.text, {}), `Heading${level}`));
+	} else if (isTokenType(token, "paragraph")) blocks.push(para(inlineToRuns(token.tokens, token.text, {})));
+	else if (isTokenType(token, "list")) blocks.push(...listBlocks(token, 0, numIds.next++));
+	else if (isTokenType(token, "table")) blocks.push(tableFromToken(token));
+	else if (isTokenType(token, "code")) for (const line of token.text.split("\n")) blocks.push(para([textRun(line.length > 0 ? line : " ", { mono: true })]));
+	else if (isTokenType(token, "blockquote")) for (const inner of blocksFromTokens(token.tokens, numIds)) {
+		const styled = inner.type === "paragraph" ? {
+			...inner,
+			formatting: {
+				...inner.formatting,
+				styleId: "Quote"
+			}
+		} : inner;
+		blocks.push(styled);
+	}
+	else if (token.type === "hr") blocks.push(para([textRun("———")]));
+	else if (token.type !== "space" && "text" in token && typeof token.text === "string" && token.text.trim().length > 0) blocks.push(para([textRun(token.text)]));
+	return blocks;
+};
+const applyMarkdownPageGeometry = (document) => {
+	const section = document.package.document.finalSectionProperties;
+	if (!section) return;
+	section.marginTop = 480;
+	section.marginBottom = 480;
+	section.marginLeft = 480;
+	section.marginRight = 480;
+	section.headerDistance = 0;
+	section.footerDistance = 0;
+};
+/**
+* Convert a markdown string to a parsed `Document`. Synchronous. The result is
+* ready to hand to the editor (`<DocxEditor document={…} />`) and to re-export
+* via {@link toMarkdown}.
+*/
+function fromMarkdown(markdown) {
+	const document = createEmptyDocument();
+	const blocks = blocksFromTokens(marked.lexer(markdown), { next: 1 });
+	if (blocks.length > 0) document.package.document.content = blocks;
+	applyMarkdownPageGeometry(document);
+	return document;
+}
+//#endregion
+export { fromMarkdown };

package/dist/markdown/headings.d.ts

@@ -0,0 +1,13 @@
+//#region src/markdown/headings.d.ts
+/**
+ * Heading-style detection from a paragraph style id. Ported from eigenpal
+ * `agent/text-utils` (PR #595) so the markdown exporter stays self-contained
+ * (folio has no `agent/text-utils` module). Word's built-in heading styles are
+ * `Heading1`…`Heading9` (and localised aliases that still contain "heading").
+ */
+/** True when the style id denotes a Word heading style. */
+declare function isHeadingStyle(styleId?: string): boolean;
+/** Extract the 1-based heading level from a style id, or undefined. */
+declare function parseHeadingLevel(styleId?: string): number | undefined;
+//#endregion
+export { isHeadingStyle, parseHeadingLevel };

package/dist/markdown/headings.js

@@ -0,0 +1,20 @@
+//#region src/markdown/headings.ts
+/**
+* Heading-style detection from a paragraph style id. Ported from eigenpal
+* `agent/text-utils` (PR #595) so the markdown exporter stays self-contained
+* (folio has no `agent/text-utils` module). Word's built-in heading styles are
+* `Heading1`…`Heading9` (and localised aliases that still contain "heading").
+*/
+/** True when the style id denotes a Word heading style. */
+function isHeadingStyle(styleId) {
+	if (!styleId) return false;
+	return styleId.toLowerCase().includes("heading");
+}
+/** Extract the 1-based heading level from a style id, or undefined. */
+function parseHeadingLevel(styleId) {
+	if (!styleId) return;
+	const digit = /heading\s*(?<level>\d)/iu.exec(styleId)?.groups?.["level"];
+	if (digit) return Number.parseInt(digit, 10);
+}
+//#endregion
+export { isHeadingStyle, parseHeadingLevel };

package/dist/markdown/images.d.ts

@@ -0,0 +1,13 @@
+import { document_d_exports } from "../types/document.js";
+import { ImageRef, RenderContext } from "./types.js";
+
+//#region src/markdown/images.d.ts
+/**
+ * Build an `ImageRef` from a `MediaFile` and store it in the context's image
+ * map. If the same `media.path` has already been registered for this render,
+ * the existing ref is returned without re-encoding base64 or assigning a new
+ * virtual path.
+ */
+declare function registerImage(ctx: RenderContext, media: document_d_exports.MediaFile, image: document_d_exports.Image | undefined, paraId: string | undefined): ImageRef;
+//#endregion
+export { registerImage };

package/dist/markdown/images.js

@@ -0,0 +1,63 @@
+//#region src/markdown/images.ts
+const MIME_TO_EXT = {
+	"image/png": "png",
+	"image/jpeg": "jpg",
+	"image/jpg": "jpg",
+	"image/gif": "gif",
+	"image/svg+xml": "svg",
+	"image/webp": "webp",
+	"image/tiff": "tiff",
+	"image/bmp": "bmp",
+	"image/x-emf": "emf",
+	"image/x-wmf": "wmf"
+};
+function extFor(mimeType, fallback) {
+	return MIME_TO_EXT[mimeType] ?? fallback;
+}
+function bytesToBase64(bytes) {
+	if (typeof Buffer !== "undefined") return Buffer.from(bytes).toString("base64");
+	return btoa(new TextDecoder("latin1").decode(bytes));
+}
+function toUint8(data) {
+	if (data instanceof Uint8Array) return data;
+	return new Uint8Array(data);
+}
+/**
+* Build an `ImageRef` from a `MediaFile` and store it in the context's image
+* map. If the same `media.path` has already been registered for this render,
+* the existing ref is returned without re-encoding base64 or assigning a new
+* virtual path.
+*/
+function registerImage(ctx, media, image, paraId) {
+	const existing = ctx.imagesByPath.get(media.path);
+	if (existing) return existing;
+	ctx.imageCounter += 1;
+	const ext = extFor(media.mimeType, "png");
+	const meta = {
+		paraId,
+		index: ctx.imageCounter,
+		originalPath: media.path,
+		mimeType: media.mimeType,
+		alt: image?.alt ?? image?.title ?? image?.filename
+	};
+	const virtualPath = ctx.opts.imagePath ? ctx.opts.imagePath(meta) : defaultVirtualPath(meta, ext);
+	const data = toUint8(media.data);
+	const base64 = media.base64 ?? bytesToBase64(data);
+	const dataUrl = media.dataUrl ?? `data:${media.mimeType};base64,${base64}`;
+	const ref = {
+		...meta,
+		data,
+		base64,
+		dataUrl,
+		virtualPath
+	};
+	ctx.images.set(virtualPath, ref);
+	ctx.imagesByPath.set(media.path, ref);
+	return ref;
+}
+function defaultVirtualPath(meta, ext) {
+	if (meta.paraId) return `./images/${meta.paraId}-img${meta.index}.${ext}`;
+	return `./images/img${meta.index}.${ext}`;
+}
+//#endregion
+export { registerImage };

package/dist/markdown/index.d.ts

@@ -0,0 +1,18 @@
+import { document_d_exports } from "../types/document.js";
+import { ImageMeta, ImageRef, MarkdownOptions, MarkdownResult } from "./types.js";
+import { fromMarkdown } from "./fromMarkdown.js";
+
+//#region src/markdown/index.d.ts
+/**
+ * Convert a parsed `Document` to a markdown string. Synchronous; pre-parse the
+ * DOCX (e.g. via the editor or `parseDocx`) before calling.
+ */
+declare function toMarkdown(doc: document_d_exports.Document, opts?: MarkdownOptions): string;
+/**
+ * Like {@link toMarkdown}, but also returns the registered images and any
+ * non-fatal warnings. Use when post-processing image bytes or surfacing
+ * diagnostics; skill bodies only need {@link toMarkdown}.
+ */
+declare function toMarkdownResult(doc: document_d_exports.Document, opts?: MarkdownOptions): MarkdownResult;
+//#endregion
+export { type ImageMeta, type ImageRef, type MarkdownOptions, type MarkdownResult, fromMarkdown, toMarkdown, toMarkdownResult };