@threadlabs/looma 0.29.15 → 0.29.17

package/editor/chunks/extensions.js

@@ -1,5 +1,5 @@
 import { n as TABLE_CELL_BACKGROUND_PRESETS } from "./table-backgrounds.js";
-import { a as assignLoomaHeadingIds, c as loomaContainerMarker, d as normalizeLoomaChipTone, f as parseLoomaAttributes, h as splitLoomaFrontmatter, i as applyLoomaCodeNotation, l as loomaHeadingSlug, m as readLoomaAttributes, n as LOOMA_CHIP_TONES, o as formatLoomaAttributes, p as parseLoomaFenceInfo, r as LOOMA_CONTAINER_NAMES, s as loomaCodeFence, u as normalizeLoomaCalloutTone } from "./markdown.js";
+import { _ as parseLoomaAttributes, b as splitLoomaFrontmatter, c as LOOMA_CONTAINER_NAMES, d as formatLoomaAttributes, f as loomaCodeFence, g as normalizeLoomaChipTone, h as normalizeLoomaCalloutTone, i as referenceDisplay, l as applyLoomaCodeNotation, m as loomaHeadingSlug, n as LoomaReferencePresentation, p as loomaContainerMarker, r as getReferenceDisplay, s as LOOMA_CHIP_TONES, t as LoomaReference, u as assignLoomaHeadingIds, v as parseLoomaFenceInfo, y as readLoomaAttributes } from "./reference-display.js";
 import { Extension, Mark, Node as Node$1, callOrReturn, canInsertNode, combineTransactionSteps, escapeForRegEx, findChildren, findChildrenInRange, findParentNodeClosestToPos, getAttributes, getChangedRanges, getExtensionField, getMarksBetween, getText, getTextSerializersFromSchema, isNodeEmpty, isNodeSelection, markInputRule, markPasteRule, mergeAttributes, nodeInputRule, textInputRule, textblockTypeInputRule, wrappingInputRule } from "@tiptap/core";
 import { NodeSelection, Plugin, PluginKey, Selection, TextSelection } from "@tiptap/pm/state";
 import { Decoration, DecorationSet } from "@tiptap/pm/view";
@@ -614,17 +614,19 @@ function normalizeTableOfContentsConfig(attributes) {
 * @contract Depth is a maximum heading level. Relative nesting follows existing
 * ancestors rather than inserting artificial entries for skipped levels.
 */
-function getTableOfContentsEntries(doc, depth = 3) {
+function getTableOfContentsEntries(doc, depth = 3, references = {}) {
 	const entries = [];
 	const ancestors = [];
 	doc.descendants((node, position) => {
 		if (node.type.name === "loomaTableOfContents") return false;
-		if (node.type.name !== "heading" || node.attrs.level > depth || !node.textContent.trim()) return;
+		if (node.type.name !== "heading" || node.attrs.level > depth) return;
+		const text = node.textBetween(0, node.content.size, "", (leaf) => leaf.type.name === "loomaReference" || leaf.type.name === "mention" ? `${leaf.type.name === "mention" ? "@" : ""}${referenceDisplay(leaf, references).label}` : String(leaf.attrs.label ?? "")).trim();
+		if (!text) return;
 		const level = Number(node.attrs.level);
 		while (ancestors.length && ancestors[ancestors.length - 1] >= level) ancestors.pop();
 		entries.push({
 			id: String(node.attrs.id ?? ""),
-			text: node.textContent.trim(),
+			text,
 			level,
 			depth: ancestors.length,
 			position
@@ -712,8 +714,8 @@ var LoomaHeadingAnchors = Extension.create({
 		return [new Plugin({ appendTransaction: (transactions, oldState, state) => transactions.some((transaction) => transaction.docChanged) ? anchorTransaction(state, oldState.doc) : null })];
 	}
 });
-function contentsHtml(doc, config) {
-	const branches = tableOfContentsTree(getTableOfContentsEntries(doc, config.depth));
+function contentsHtml(doc, config, references = {}) {
+	const branches = tableOfContentsTree(getTableOfContentsEntries(doc, config.depth, references));
 	const list = (items) => [
 		config.format === "plain" ? "div" : config.format === "numbered" ? "ol" : "ul",
 		{ role: "list" },
@@ -755,7 +757,7 @@ function contentsHtml(doc, config) {
 async function navigateTableOfContents(editor, id) {
 	const target = [...editor.view.dom.querySelectorAll("h1[id], h2[id], h3[id]")].find((heading) => heading.id === id);
 	if (!target) return;
-	const entry = getTableOfContentsEntries(editor.state.doc).find((heading) => heading.id === id);
+	const entry = getTableOfContentsEntries(editor.state.doc, 3, getReferenceDisplay(editor)).find((heading) => heading.id === id);
 	if (entry) await revealLoomaExpandAt(editor, entry.position + 1);
 	if (!target.isConnected || editor.isDestroyed) return;
 	target.scrollIntoView({
@@ -836,7 +838,7 @@ var LoomaTableOfContents = Node$1.create({
 					nav.append(DOMSerializer.fromSchema(editor.schema).serializeFragment(current.content));
 					dom.replaceChildren(nav);
 				} else {
-					const { dom: content } = DOMSerializer.renderSpec(document, contentsHtml(editor.state.doc, normalizeTableOfContentsConfig(current.attrs)));
+					const { dom: content } = DOMSerializer.renderSpec(document, contentsHtml(editor.state.doc, normalizeTableOfContentsConfig(current.attrs), getReferenceDisplay(editor)));
 					dom.replaceChildren(content);
 				}
 			};
@@ -6764,10 +6766,36 @@ var EMPTY_STATE$1 = {
 * than document data.
 */
 var LoomaMentionSuggestionPluginKey = new PluginKey("loomaMentionSuggestion");
-var LoomaMentionNode = Mention.extend({ addAttributes() {
-	const { mentionSuggestionChar: _trigger, ...durableAttributes } = this.parent?.() ?? {};
-	return durableAttributes;
-} });
+var LoomaMentionNode = Mention.extend({
+	renderText(props) {
+		const { node } = props;
+		const label = this.editor && getReferenceDisplay(this.editor)[`mention:${node.attrs.id}`]?.label;
+		return this.parent({
+			...props,
+			node: typeof label === "string" ? node.type.create({
+				...node.attrs,
+				label
+			}, node.content, node.marks) : node
+		});
+	},
+	renderHTML({ node, HTMLAttributes }) {
+		const label = this.editor && getReferenceDisplay(this.editor)[`mention:${node.attrs.id}`]?.label;
+		return this.parent({
+			node: typeof label === "string" ? node.type.create({
+				...node.attrs,
+				label
+			}, node.content, node.marks) : node,
+			HTMLAttributes: typeof label === "string" ? {
+				...HTMLAttributes,
+				"data-label": label
+			} : HTMLAttributes
+		});
+	},
+	addAttributes() {
+		const { mentionSuggestionChar: _trigger, ...durableAttributes } = this.parent?.() ?? {};
+		return durableAttributes;
+	}
+});
 async function resolveMentionItems(source, query, limit) {
 	try {
 		return filterLoomaMentionItems(typeof source === "function" ? await source(query, { limit }) : source ?? [], query, limit);
@@ -9934,6 +9962,11 @@ var NODES = {
 	mention: (state, node) => {
 		const id = String(node.attrs.id ?? "");
 		state.write(`:mention[${label(String(node.attrs.label ?? id))}]${formatLoomaAttributes({ id }, { hashId: false })}`);
+	},
+	loomaReference: (state, node) => {
+		const wrapper = document.createElement("span");
+		wrapper.append(DOMSerializer.fromSchema(node.type.schema).serializeNode(node));
+		state.write(wrapper.innerHTML);
 	}
 };
 var MARKS = {
@@ -10775,6 +10808,11 @@ function getDefaultEditorExtensions(options = {}) {
 		Document,
 		Paragraph,
 		Text$1,
+		LoomaReference,
+		LoomaReferencePresentation.configure({
+			references: options.references ?? {},
+			mentions: options.references !== void 0
+		}),
 		Bold,
 		Italic,
 		Strike,

package/editor/chunks/{markdown.js → reference-display.js}

@@ -1,3 +1,5 @@
+import { Extension, Node, mergeAttributes } from "@tiptap/core";
+import { NodeSelection, Plugin, PluginKey } from "@tiptap/pm/state";
 //#region src/markdown/index.ts
 /**
 * Callout tones a document stores, in the order the editor offers them. The Callout component also
@@ -239,4 +241,208 @@ function loomaCodeFence(code) {
 	return "`".repeat(Math.max(3, longest + 1));
 }
 //#endregion
-export { assignLoomaHeadingIds as a, loomaContainerMarker as c, normalizeLoomaChipTone as d, parseLoomaAttributes as f, splitLoomaFrontmatter as h, applyLoomaCodeNotation as i, loomaHeadingSlug as l, readLoomaAttributes as m, LOOMA_CHIP_TONES as n, formatLoomaAttributes as o, parseLoomaFenceInfo as p, LOOMA_CONTAINER_NAMES as r, loomaCodeFence as s, LOOMA_CALLOUT_TONES as t, normalizeLoomaCalloutTone as u };
+//#region src/editor/content.ts
+/**
+* A link destination the editor may store: a site-relative path, fragment, or query, or an
+* absolute http, https, mailto, or tel URL.
+*
+* @failure Returns null for empty input, control characters, other schemes, and unparseable URLs.
+*/
+function validLinkHref(value) {
+	const href = value.trim();
+	if (!href || /[\u0000-\u001f\u007f]/.test(href)) return null;
+	if (/^(\/|#|\?)/.test(href)) return href;
+	try {
+		const url = new URL(href);
+		return [
+			"http:",
+			"https:",
+			"mailto:",
+			"tel:"
+		].includes(url.protocol) ? href : null;
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region src/editor/reference-display.ts
+var referenceDisplayKey = new PluginKey("loomaReferenceDisplay");
+var referenceDisplayMeta = "loomaReferenceDisplay";
+/**
+* Replaces presentation without editing the document or adding an undo/history entry.
+* @lifecycle Values last until the next replacement or editor destruction; hosts own persistence.
+*/
+function setReferenceDisplay(editor, references) {
+	if (editor.isDestroyed) return;
+	editor.storage.loomaReferencePresentation?.enableMentions?.();
+	editor.view.dispatch(editor.state.tr.setMeta(referenceDisplayMeta, references).setMeta("addToHistory", false));
+}
+/**
+* The current replaceable presentation; absent entries use the saved fallback.
+* @ownership The returned map belongs to the host; replace it rather than mutating it.
+*/
+function getReferenceDisplay(editor) {
+	return editor.storage.loomaReferencePresentation?.references ?? {};
+}
+/**
+* Reads current host presentation, with a durable insertion-time fallback for offline copies.
+* @failure Unsafe cached destinations fall back to the saved safe URL or no destination.
+*/
+function referenceDisplay(node, references = {}) {
+	const kind = node.type.name === "mention" ? "mention" : node.attrs.kind;
+	const display = references[`${kind}:${node.attrs.id}`];
+	const label = typeof display?.label === "string" ? display.label : typeof node.attrs.label === "string" ? node.attrs.label : String(node.attrs.id ?? "Reference");
+	const href = typeof display?.href === "string" ? validLinkHref(display.href) : null;
+	return {
+		label,
+		...kind === "link" ? { href: href ?? (typeof node.attrs.href === "string" ? validLinkHref(node.attrs.href) : null) ?? void 0 } : {}
+	};
+}
+/**
+* An automatically labelled link; custom wording remains an ordinary text link.
+* @contract Identity and insertion-time fallback stay in JSON; cached presentation stays outside it.
+*/
+var LoomaReference = Node.create({
+	name: "loomaReference",
+	inline: true,
+	group: "inline",
+	atom: true,
+	addAttributes: () => ({
+		id: {
+			default: null,
+			renderHTML: () => ({})
+		},
+		kind: {
+			default: "link",
+			renderHTML: () => ({})
+		},
+		href: {
+			default: null,
+			renderHTML: () => ({})
+		},
+		label: {
+			default: null,
+			renderHTML: () => ({})
+		},
+		target: {
+			default: "_self",
+			renderHTML: () => ({})
+		}
+	}),
+	parseHTML: () => [{
+		tag: "a[data-looma-reference]",
+		priority: 1001,
+		getAttrs: (element) => ({
+			id: element.getAttribute("data-looma-reference"),
+			kind: "link",
+			href: element.getAttribute("href"),
+			label: element.textContent,
+			target: element.getAttribute("target") ?? "_self"
+		})
+	}],
+	renderHTML({ node, HTMLAttributes }) {
+		const display = referenceDisplay(node, this.editor ? getReferenceDisplay(this.editor) : {});
+		return [
+			"a",
+			mergeAttributes(HTMLAttributes, {
+				"data-looma-reference": node.attrs.id,
+				href: display.href,
+				target: node.attrs.target === "_blank" ? "_blank" : "_self",
+				rel: "noopener noreferrer"
+			}),
+			display.label
+		];
+	},
+	renderText({ node }) {
+		return referenceDisplay(node, this.editor ? getReferenceDisplay(this.editor) : {}).label;
+	}
+});
+/**
+* Installs metadata-backed node views for references and existing stable-id mentions.
+* @lifecycle Node views register until destroyed, including across editor reattachment.
+*/
+var LoomaReferencePresentation = Extension.create({
+	name: "loomaReferencePresentation",
+	addOptions: () => ({
+		references: {},
+		mentions: false
+	}),
+	addStorage() {
+		return { references: this.options.references };
+	},
+	addProseMirrorPlugins() {
+		const initial = this.options.references;
+		const refresh = /* @__PURE__ */ new Set();
+		const nodeView = (node, view, getPosition) => {
+			let current = node;
+			const mention = node.type.name === "mention";
+			const dom = document.createElement(mention ? "span" : "a");
+			if (mention) {
+				dom.className = "looma-mention";
+				dom.setAttribute("data-type", "mention");
+			} else dom.addEventListener("click", (event) => {
+				if (!(event instanceof MouseEvent) || !view.editable || event.metaKey || event.ctrlKey) return;
+				const position = getPosition();
+				if (position === void 0) return;
+				event.preventDefault();
+				view.dispatch(view.state.tr.setSelection(NodeSelection.create(view.state.doc, position)));
+				view.focus();
+			});
+			const render = () => {
+				const display = referenceDisplay(current, referenceDisplayKey.getState(view.state));
+				dom.textContent = `${mention ? "@" : ""}${display.label}`;
+				if (mention) {
+					dom.setAttribute("data-id", current.attrs.id ?? "");
+					dom.setAttribute("data-label", display.label);
+				}
+				if (!mention) {
+					dom.setAttribute("data-looma-reference", current.attrs.id ?? "");
+					if (display.href) dom.setAttribute("href", display.href);
+					else dom.removeAttribute("href");
+					dom.setAttribute("target", current.attrs.target === "_blank" ? "_blank" : "_self");
+					dom.setAttribute("rel", "noopener noreferrer");
+				}
+			};
+			refresh.add(render);
+			render();
+			return {
+				dom,
+				update(next) {
+					if (next.type !== current.type) return false;
+					current = next;
+					render();
+					return true;
+				},
+				destroy: () => {
+					refresh.delete(render);
+				}
+			};
+		};
+		const nodeViews = {
+			loomaReference: nodeView,
+			...this.options.mentions && this.editor.schema.nodes.mention ? { mention: nodeView } : {}
+		};
+		this.storage.enableMentions = () => {
+			if (nodeViews.mention || !this.editor.schema.nodes.mention) return;
+			nodeViews.mention = nodeView;
+			this.editor.view.setProps({ nodeViews: { ...this.editor.view.props.nodeViews } });
+		};
+		return [new Plugin({
+			key: referenceDisplayKey,
+			state: {
+				init: () => initial,
+				apply: (transaction, previous) => {
+					const next = transaction.getMeta(referenceDisplayMeta) ?? previous;
+					this.storage.references = next;
+					return next;
+				}
+			},
+			props: { nodeViews },
+			view: () => ({ update: (view, previous) => {
+				if (referenceDisplayKey.getState(view.state) !== referenceDisplayKey.getState(previous)) refresh.forEach((render) => render());
+			} })
+		})];
+	}
+});
+//#endregion
+export { parseLoomaAttributes as _, setReferenceDisplay as a, splitLoomaFrontmatter as b, LOOMA_CONTAINER_NAMES as c, formatLoomaAttributes as d, loomaCodeFence as f, normalizeLoomaChipTone as g, normalizeLoomaCalloutTone as h, referenceDisplay as i, applyLoomaCodeNotation as l, loomaHeadingSlug as m, LoomaReferencePresentation as n, LOOMA_CALLOUT_TONES as o, loomaContainerMarker as p, getReferenceDisplay as r, LOOMA_CHIP_TONES as s, LoomaReference as t, assignLoomaHeadingIds as u, parseLoomaFenceInfo as v, readLoomaAttributes as y };

package/editor/expressmark.d.ts

@@ -1,5 +1,10 @@
-import type { JSONContent } from "@tiptap/core";
+import type { Editor, JSONContent } from "@tiptap/core";
 import { type ConversionOptions, type Document } from "expressmark";
+import { type LoomaReferenceMap } from "./reference-display.js";
+/** Conversion-time display snapshot, independent from the authored editor document. */
+export interface EditorMarkdownConversionOptions extends ConversionOptions {
+    references?: LoomaReferenceMap;
+}
 /**
  * A conversion cannot faithfully represent the named input at this document location.
  * @failure Callers retain the original document and can report the unsupported feature and path.
@@ -13,7 +18,7 @@ export declare class EditorMarkdownConversionError extends Error {
  * Maps an editor's saved JSON to the independent Expressive Markdown AST without DOM access.
  * @contract Unsupported nodes, marks and durable attributes throw with their location; input is never mutated.
  */
-export declare function editorDocumentToExpressmark(document: JSONContent, options?: ConversionOptions): Document;
+export declare function editorDocumentToExpressmark(document: JSONContent, options?: EditorMarkdownConversionOptions): Document;
 /**
  * Maps supported Expressive Markdown content into the Looma editor's saved JSON shape.
  * @contract The editor schema cannot represent arbitrary format extensions; unsupported meanings fail explicitly.
@@ -23,7 +28,12 @@ export declare function expressmarkToEditorDocument(document: Document): JSONCon
  * Writes an editor document using Expressmark's shared parser/writer and safe HTML policy.
  * @failure Unsupported editor data raises EditorMarkdownConversionError before any input is changed.
  */
-export declare function editorDocumentToMarkdown(document: JSONContent, options?: ConversionOptions): string;
+export declare function editorDocumentToMarkdown(document: JSONContent, options?: EditorMarkdownConversionOptions): string;
+/**
+ * Serializes the current editor, including its current display cache and concrete TOC entries.
+ * @failure Unsupported content throws EditorMarkdownConversionError without changing the document.
+ */
+export declare function editorToMarkdown(editor: Editor, options?: ConversionOptions): string;
 /**
  * Parses Expressive Markdown into editable JSON for the supported editor schema.
  * @failure Unsupported content or root metadata stops conversion instead of being silently flattened.

package/editor/expressmark.js

@@ -1,4 +1,4 @@
-import { l as loomaHeadingSlug, n as LOOMA_CHIP_TONES, t as LOOMA_CALLOUT_TONES } from "./chunks/markdown.js";
+import { m as loomaHeadingSlug, o as LOOMA_CALLOUT_TONES, r as getReferenceDisplay, s as LOOMA_CHIP_TONES } from "./chunks/reference-display.js";
 import { parse, stringify } from "expressmark";
 //#region src/editor/expressmark.ts
 /**
@@ -179,6 +179,11 @@ function legacyCodePresentation(code, path) {
 	return result;
 }
 var REVERSE_MARKS = Object.fromEntries(Object.entries(MARKS).map(([left, right]) => [right, left]));
+var displayText = (node, references) => {
+	if (node.type === "loomaReference") return references[`link:${node.attrs?.id}`]?.label ?? string(node.attrs?.label, string(node.attrs?.id));
+	if (node.type === "mention") return `@${references[`mention:${node.attrs?.id}`]?.label ?? string(node.attrs?.label, string(node.attrs?.id))}`;
+	return node.text ?? (node.content ?? []).map((child) => displayText(child, references)).join("");
+};
 function tocBody(headings, depth, ordered) {
 	const roots = [];
 	const stack = [];
@@ -225,6 +230,7 @@ function toNode(node, path, context) {
 	if (![
 		"text",
 		"mention",
+		"loomaReference",
 		"loomaChip",
 		"hardBreak"
 	].includes(node.type ?? "")) fail(path, "marks on a block node");
@@ -281,6 +287,29 @@ function toBareNode(node, path, context) {
 		};
 	};
 	switch (node.type) {
+		case "loomaReference": {
+			fields(node, [
+				"id",
+				"kind",
+				"href",
+				"label",
+				"target"
+			], path);
+			if (!attrs.id || attrs.kind !== "link") fail(path, "invalid link reference identity");
+			const display = context.references[`link:${attrs.id}`];
+			const href = display?.href ?? string(attrs.href);
+			safeNavigation(href, false, path);
+			return {
+				type: "link",
+				url: href,
+				value: display?.label ?? string(attrs.label, string(attrs.id)),
+				attributes: {
+					ref: string(attrs.id),
+					target: string(attrs.target, "_self"),
+					rel: "noopener noreferrer"
+				}
+			};
+		}
 		case "text":
 			fields(node, [], path);
 			return {
@@ -355,7 +384,7 @@ function toBareNode(node, path, context) {
 			return {
 				type: "inline",
 				subType: "mention",
-				value: string(attrs.label, string(attrs.id)),
+				value: context.references[`mention:${attrs.id}`]?.label ?? string(attrs.label, string(attrs.id)),
 				...attrs.id ? { ref: string(attrs.id) } : {}
 			};
 		case "loomaChip":
@@ -523,7 +552,7 @@ function editorDocumentToExpressmark(document, options = {}) {
 		if (!insideToc && node.type === "loomaTableOfContents" && !node.content?.length) automaticToc = true;
 		if (!insideToc && node.type === "heading") headings.push({
 			node,
-			text: (node.content ?? []).map((child) => child.text ?? "").join(""),
+			text: displayText(node, options.references ?? {}),
 			id: string(node.attrs?.id),
 			level: Number(node.attrs?.level ?? 1)
 		});
@@ -553,7 +582,8 @@ function editorDocumentToExpressmark(document, options = {}) {
 	}
 	const context = {
 		headings,
-		headingIds
+		headingIds,
+		references: options.references ?? {}
 	};
 	return {
 		type: "document",
@@ -601,8 +631,23 @@ function fromNode(node, path, marks = []) {
 		check(node.type === "link" ? [
 			"target",
 			"rel",
-			"class"
+			"class",
+			"ref"
 		] : []);
+		if (node.type === "link" && attrs.ref !== void 0) {
+			if (typeof attrs.ref !== "string" || !attrs.ref || node.title || attrs.class || content(node).some((child) => child.type !== "text" || child.attributes || child.id)) fail(path, "formatted or invalid link reference");
+			return [{
+				type: "loomaReference",
+				attrs: {
+					id: attrs.ref,
+					kind: "link",
+					href: node.url ?? "",
+					label: text(node),
+					target: attrs.target ?? "_self"
+				},
+				...marks.length ? { marks } : {}
+			}];
+		}
 		const mark = { type: REVERSE_MARKS[node.type] };
 		if (node.type === "link") mark.attrs = {
 			href: node.url ?? "",
@@ -932,6 +977,16 @@ function editorDocumentToMarkdown(document, options = {}) {
 	return stringify(editorDocumentToExpressmark(document, options), options);
 }
 /**
+* Serializes the current editor, including its current display cache and concrete TOC entries.
+* @failure Unsupported content throws EditorMarkdownConversionError without changing the document.
+*/
+function editorToMarkdown(editor, options = {}) {
+	return editorDocumentToMarkdown(editor.getJSON(), {
+		...options,
+		references: getReferenceDisplay(editor)
+	});
+}
+/**
 * Parses Expressive Markdown into editable JSON for the supported editor schema.
 * @failure Unsupported content or root metadata stops conversion instead of being silently flattened.
 */
@@ -939,4 +994,4 @@ function markdownToEditorDocument(markdown, options = {}) {
 	return expressmarkToEditorDocument(parse(markdown, options));
 }
 //#endregion
-export { EditorMarkdownConversionError, editorDocumentToExpressmark, editorDocumentToMarkdown, expressmarkToEditorDocument, markdownToEditorDocument };
+export { EditorMarkdownConversionError, editorDocumentToExpressmark, editorDocumentToMarkdown, editorToMarkdown, expressmarkToEditorDocument, markdownToEditorDocument };

package/editor/extensions/index.d.ts

@@ -15,6 +15,7 @@ export { LoomaTab, LoomaTabs } from "./tabs.js";
 export { LoomaTableOfContents, getTableOfContentsEntries, normalizeTableOfContentsConfig, type LoomaTableOfContentsConfig, type LoomaTableOfContentsEntry, type LoomaTableOfContentsFormat, } from "./table-of-contents.js";
 export { getDefaultEditorExtensions, getLoomaTableExtensions, LoomaTableKit, type DefaultEditorExtensionsOptions, type LoomaCodeLanguages, } from "./preset.js";
 export { LoomaSmartPaste } from "./smart-paste.js";
+export { LoomaReference, LoomaReferencePresentation, setReferenceDisplay, getReferenceDisplay, referenceDisplay, type LoomaReferenceDisplay, type LoomaReferenceMap } from "../reference-display.js";
 export { loomaMarkdownFromDoc, loomaMarkdownToHtml } from "./markdown.js";
 export { getActiveTableUiState, handleTableAction, handleTableOverlayAction, insertTableAtRange, normalizeActiveTableColumnWidths, shouldShowTextFormattingToolbar, type ActiveTableUiState, type InsertTableAtRangeOptions, type TableActionCapabilities, } from "./table-commands.js";
 export { LoomaTable, getActiveTableCellAlignment, getActiveTableCellBackground, LoomaTableCell, LoomaTableHeader, setActiveTableCellAlignment, setActiveTableCellBackground, TABLE_CELL_BACKGROUND_PRESETS, type TableCellAlignment, type TableCellBackground, } from "./table-formatting.js";

package/editor/extensions/index.js

@@ -1,4 +1,4 @@
 import { n as TABLE_CELL_BACKGROUND_PRESETS } from "../chunks/table-backgrounds.js";
 import { A as filterLoomaMentionItems, B as LoomaFigcaption, C as loomaMarkdownToHtml, D as createLoomaMentionExtension, E as LoomaMentionSuggestionPluginKey, F as LoomaTableOfContents, G as LoomaChip, H as LoomaExpand, I as getTableOfContentsEntries, J as LOOMA_ACTIVE_BLOCK_BLUR_GRACE_MS, K as normalizeLoomaChipColor, L as normalizeTableOfContentsConfig, M as LoomaImage, N as normalizeImageDimension, O as DEFAULT_MENTION_RESULT_LIMIT, P as normalizeImagePlacement, Q as LoomaActiveBlockPluginKey, R as LoomaTab, S as loomaMarkdownFromDoc, T as siteRelativeHref, U as revealLoomaExpandAt, V as LoomaFigure, W as LOOMA_CHIP_COLORS, X as LOOMA_ACTIVE_BLOCK_TYPING_IDLE_MS, Y as LOOMA_ACTIVE_BLOCK_CLASS, Z as LoomaActiveBlock, _ as getActiveTableCellAlignment, a as getActiveTableUiState, b as setActiveTableCellBackground, c as insertTableAtRange, d as LoomaTableKit, f as getDefaultEditorExtensions, g as LoomaTableHeader, h as LoomaTableCell, i as getDefaultSlashCommands, j as normalizeMentionResultLimit, k as MAX_MENTION_RESULT_LIMIT, l as normalizeActiveTableColumnWidths, m as LoomaTable, n as createLoomaSlashCommandExtension, o as handleTableAction, p as getLoomaTableExtensions, q as LoomaCallout, r as filterLoomaSlashCommands, s as handleTableOverlayAction, t as LoomaSlashCommand, u as shouldShowTextFormattingToolbar, v as getActiveTableCellBackground, w as createSiteRelativeLinks, x as LoomaSmartPaste, y as setActiveTableCellAlignment, z as LoomaTabs } from "../chunks/extensions.js";
-import { t as LOOMA_CALLOUT_TONES } from "../chunks/markdown.js";
-export { DEFAULT_MENTION_RESULT_LIMIT, LOOMA_ACTIVE_BLOCK_BLUR_GRACE_MS, LOOMA_ACTIVE_BLOCK_CLASS, LOOMA_ACTIVE_BLOCK_TYPING_IDLE_MS, LOOMA_CALLOUT_TONES, LOOMA_CHIP_COLORS, LoomaActiveBlock, LoomaActiveBlockPluginKey, LoomaCallout, LoomaChip, LoomaExpand, LoomaFigcaption, LoomaFigure, LoomaImage, LoomaMentionSuggestionPluginKey, LoomaSlashCommand, LoomaSmartPaste, LoomaTab, LoomaTable, LoomaTableCell, LoomaTableHeader, LoomaTableKit, LoomaTableOfContents, LoomaTabs, MAX_MENTION_RESULT_LIMIT, TABLE_CELL_BACKGROUND_PRESETS, createLoomaMentionExtension, createLoomaSlashCommandExtension, createSiteRelativeLinks, filterLoomaMentionItems, filterLoomaSlashCommands, getActiveTableCellAlignment, getActiveTableCellBackground, getActiveTableUiState, getDefaultEditorExtensions, getDefaultSlashCommands, getLoomaTableExtensions, getTableOfContentsEntries, handleTableAction, handleTableOverlayAction, insertTableAtRange, loomaMarkdownFromDoc, loomaMarkdownToHtml, normalizeActiveTableColumnWidths, normalizeImageDimension, normalizeImagePlacement, normalizeLoomaChipColor, normalizeMentionResultLimit, normalizeTableOfContentsConfig, revealLoomaExpandAt, setActiveTableCellAlignment, setActiveTableCellBackground, shouldShowTextFormattingToolbar, siteRelativeHref };
+import { a as setReferenceDisplay, i as referenceDisplay, n as LoomaReferencePresentation, o as LOOMA_CALLOUT_TONES, r as getReferenceDisplay, t as LoomaReference } from "../chunks/reference-display.js";
+export { DEFAULT_MENTION_RESULT_LIMIT, LOOMA_ACTIVE_BLOCK_BLUR_GRACE_MS, LOOMA_ACTIVE_BLOCK_CLASS, LOOMA_ACTIVE_BLOCK_TYPING_IDLE_MS, LOOMA_CALLOUT_TONES, LOOMA_CHIP_COLORS, LoomaActiveBlock, LoomaActiveBlockPluginKey, LoomaCallout, LoomaChip, LoomaExpand, LoomaFigcaption, LoomaFigure, LoomaImage, LoomaMentionSuggestionPluginKey, LoomaReference, LoomaReferencePresentation, LoomaSlashCommand, LoomaSmartPaste, LoomaTab, LoomaTable, LoomaTableCell, LoomaTableHeader, LoomaTableKit, LoomaTableOfContents, LoomaTabs, MAX_MENTION_RESULT_LIMIT, TABLE_CELL_BACKGROUND_PRESETS, createLoomaMentionExtension, createLoomaSlashCommandExtension, createSiteRelativeLinks, filterLoomaMentionItems, filterLoomaSlashCommands, getActiveTableCellAlignment, getActiveTableCellBackground, getActiveTableUiState, getDefaultEditorExtensions, getDefaultSlashCommands, getLoomaTableExtensions, getReferenceDisplay, getTableOfContentsEntries, handleTableAction, handleTableOverlayAction, insertTableAtRange, loomaMarkdownFromDoc, loomaMarkdownToHtml, normalizeActiveTableColumnWidths, normalizeImageDimension, normalizeImagePlacement, normalizeLoomaChipColor, normalizeMentionResultLimit, normalizeTableOfContentsConfig, referenceDisplay, revealLoomaExpandAt, setActiveTableCellAlignment, setActiveTableCellBackground, setReferenceDisplay, shouldShowTextFormattingToolbar, siteRelativeHref };

package/editor/extensions/preset.d.ts

@@ -4,6 +4,7 @@
  */
 import { type AnyExtension, type NodeViewRenderer } from "@tiptap/core";
 import { createLowlight } from "lowlight";
+import { type LoomaReferenceMap } from "../reference-display.js";
 /** Grammars supplied by the host; importing a language remains the host's choice. */
 export type LoomaCodeLanguages = NonNullable<Parameters<typeof createLowlight>[0]>;
 /**
@@ -12,6 +13,8 @@ export type LoomaCodeLanguages = NonNullable<Parameters<typeof createLowlight>[0
  * rather than relying on undocumented mutation of the returned extensions.
  */
 export interface DefaultEditorExtensionsOptions {
+    /** Replaceable display data; updating it must use setReferenceDisplay, never setContent. */
+    references?: LoomaReferenceMap;
     /** Placeholder shown only for empty paragraphs, not every empty node type. */
     placeholder?: string;
     /** Passed to Tiptap Link; defaults false to keep editing clicks in the editor. */

package/editor/extensions/table-of-contents.d.ts

@@ -1,5 +1,6 @@
 import { Node, type NodeViewRenderer } from "@tiptap/core";
 import { type Node as ProseMirrorNode } from "@tiptap/pm/model";
+import { type LoomaReferenceMap } from "../reference-display.js";
 /** Formatting affects presentation only; heading order remains document order. */
 export type LoomaTableOfContentsFormat = "plain" | "bulleted" | "numbered";
 /** Persisted TOC choices; entries themselves are always derived from headings. */
@@ -26,7 +27,7 @@ export declare function normalizeTableOfContentsConfig(attributes: Record<string
  * @contract Depth is a maximum heading level. Relative nesting follows existing
  * ancestors rather than inserting artificial entries for skipped levels.
  */
-export declare function getTableOfContentsEntries(doc: ProseMirrorNode, depth?: number): LoomaTableOfContentsEntry[];
+export declare function getTableOfContentsEntries(doc: ProseMirrorNode, depth?: number, references?: LoomaReferenceMap): LoomaTableOfContentsEntry[];
 interface Branch {
     entry: LoomaTableOfContentsEntry;
     children: Branch[];

package/editor/index.js

@@ -1,7 +1,7 @@
 import { n as TABLE_CELL_BACKGROUND_PRESETS, t as TABLE_CELL_BACKGROUND_OPTIONS } from "./chunks/table-backgrounds.js";
 import { n as resolveTableCellAt, t as measureTableOverlayGeometry } from "./chunks/ui.js";
 import { A as filterLoomaMentionItems, B as LoomaFigcaption, C as loomaMarkdownToHtml, D as createLoomaMentionExtension, E as LoomaMentionSuggestionPluginKey, F as LoomaTableOfContents, G as LoomaChip, H as LoomaExpand, I as getTableOfContentsEntries, J as LOOMA_ACTIVE_BLOCK_BLUR_GRACE_MS, K as normalizeLoomaChipColor, L as normalizeTableOfContentsConfig, M as LoomaImage, N as normalizeImageDimension, O as DEFAULT_MENTION_RESULT_LIMIT, P as normalizeImagePlacement, Q as LoomaActiveBlockPluginKey, R as LoomaTab, S as loomaMarkdownFromDoc, T as siteRelativeHref, U as revealLoomaExpandAt, V as LoomaFigure, W as LOOMA_CHIP_COLORS, X as LOOMA_ACTIVE_BLOCK_TYPING_IDLE_MS, Y as LOOMA_ACTIVE_BLOCK_CLASS, Z as LoomaActiveBlock, _ as getActiveTableCellAlignment, a as getActiveTableUiState, b as setActiveTableCellBackground, c as insertTableAtRange, d as LoomaTableKit, f as getDefaultEditorExtensions, g as LoomaTableHeader, h as LoomaTableCell, i as getDefaultSlashCommands, j as normalizeMentionResultLimit, k as MAX_MENTION_RESULT_LIMIT, l as normalizeActiveTableColumnWidths, m as LoomaTable, n as createLoomaSlashCommandExtension, o as handleTableAction, p as getLoomaTableExtensions, q as LoomaCallout, r as filterLoomaSlashCommands, s as handleTableOverlayAction, t as LoomaSlashCommand, u as shouldShowTextFormattingToolbar, v as getActiveTableCellBackground, w as createSiteRelativeLinks, x as LoomaSmartPaste, y as setActiveTableCellAlignment, z as LoomaTabs } from "./chunks/extensions.js";
-import { t as LOOMA_CALLOUT_TONES } from "./chunks/markdown.js";
+import { a as setReferenceDisplay, i as referenceDisplay, n as LoomaReferencePresentation, o as LOOMA_CALLOUT_TONES, r as getReferenceDisplay, t as LoomaReference } from "./chunks/reference-display.js";
 import { AlignCenter, AlignLeft, AlignRight, ArrowLeft, Bell, Bold, BookUser, Braces, Calculator, Check, ChevronDown, ChevronLeft, ChevronRight, CircleCheck, CircleDot, CircleQuestionMark, CircleX, CodeXml, Columns3, Compass, CreditCard, Ellipsis, Eraser, ExternalLink, FileText, Folder, GripHorizontal, GripVertical, Heading1, Heading2, Heading3, Highlighter, History, Image, Info, Italic, LayoutDashboard, Lightbulb, Link, List, ListOrdered, ListTodo, LoaderCircle, Merge, MessageSquareWarning, Minus, NotebookPen, PaintBucket, PanelBottom, PanelLeft, PanelRight, PanelTop, Pencil, Pilcrow, Plus, Quote, Receipt, Redo2, Rows3, Search, Settings, Split, Strikethrough, Table2, Tag, Trash2, TriangleAlert, Truck, Underline, Undo2, Unlink, UserRound, Users, X } from "lucide";
 //#region src/editor/icons.ts
 /** The opinionated Lucide set used by Looma's shipped interaction surfaces. */
@@ -124,4 +124,4 @@ function getVisualViewportRect(owner = window) {
 	};
 }
 //#endregion
-export { DEFAULT_MENTION_RESULT_LIMIT, LOOMA_ACTIVE_BLOCK_BLUR_GRACE_MS, LOOMA_ACTIVE_BLOCK_CLASS, LOOMA_ACTIVE_BLOCK_TYPING_IDLE_MS, LOOMA_CALLOUT_TONES, LOOMA_CHIP_COLORS, LOOMA_ICONS, LoomaActiveBlock, LoomaActiveBlockPluginKey, LoomaCallout, LoomaChip, LoomaExpand, LoomaFigcaption, LoomaFigure, LoomaImage, LoomaMentionSuggestionPluginKey, LoomaSlashCommand, LoomaSmartPaste, LoomaTab, LoomaTable, LoomaTableCell, LoomaTableHeader, LoomaTableKit, LoomaTableOfContents, LoomaTabs, MAX_MENTION_RESULT_LIMIT, TABLE_CELL_BACKGROUND_OPTIONS, TABLE_CELL_BACKGROUND_PRESETS, createLoomaMentionExtension, createLoomaSlashCommandExtension, createSiteRelativeLinks, filterLoomaMentionItems, filterLoomaSlashCommands, getActiveTableCellAlignment, getActiveTableCellBackground, getActiveTableUiState, getDefaultEditorExtensions, getDefaultSlashCommands, getLoomaTableExtensions, getTableOfContentsEntries, getVisualViewportRect, handleTableAction, handleTableOverlayAction, insertTableAtRange, loomaIconMarkup, loomaMarkdownFromDoc, loomaMarkdownToHtml, measureTableOverlayGeometry, normalizeActiveTableColumnWidths, normalizeImageDimension, normalizeImagePlacement, normalizeLoomaChipColor, normalizeMentionResultLimit, normalizeTableOfContentsConfig, resolveTableCellAt, revealLoomaExpandAt, setActiveTableCellAlignment, setActiveTableCellBackground, shouldShowTextFormattingToolbar, siteRelativeHref };
+export { DEFAULT_MENTION_RESULT_LIMIT, LOOMA_ACTIVE_BLOCK_BLUR_GRACE_MS, LOOMA_ACTIVE_BLOCK_CLASS, LOOMA_ACTIVE_BLOCK_TYPING_IDLE_MS, LOOMA_CALLOUT_TONES, LOOMA_CHIP_COLORS, LOOMA_ICONS, LoomaActiveBlock, LoomaActiveBlockPluginKey, LoomaCallout, LoomaChip, LoomaExpand, LoomaFigcaption, LoomaFigure, LoomaImage, LoomaMentionSuggestionPluginKey, LoomaReference, LoomaReferencePresentation, LoomaSlashCommand, LoomaSmartPaste, LoomaTab, LoomaTable, LoomaTableCell, LoomaTableHeader, LoomaTableKit, LoomaTableOfContents, LoomaTabs, MAX_MENTION_RESULT_LIMIT, TABLE_CELL_BACKGROUND_OPTIONS, TABLE_CELL_BACKGROUND_PRESETS, createLoomaMentionExtension, createLoomaSlashCommandExtension, createSiteRelativeLinks, filterLoomaMentionItems, filterLoomaSlashCommands, getActiveTableCellAlignment, getActiveTableCellBackground, getActiveTableUiState, getDefaultEditorExtensions, getDefaultSlashCommands, getLoomaTableExtensions, getReferenceDisplay, getTableOfContentsEntries, getVisualViewportRect, handleTableAction, handleTableOverlayAction, insertTableAtRange, loomaIconMarkup, loomaMarkdownFromDoc, loomaMarkdownToHtml, measureTableOverlayGeometry, normalizeActiveTableColumnWidths, normalizeImageDimension, normalizeImagePlacement, normalizeLoomaChipColor, normalizeMentionResultLimit, normalizeTableOfContentsConfig, referenceDisplay, resolveTableCellAt, revealLoomaExpandAt, setActiveTableCellAlignment, setActiveTableCellBackground, setReferenceDisplay, shouldShowTextFormattingToolbar, siteRelativeHref };

package/editor/link-editing.d.ts

@@ -1,4 +1,7 @@
 import type { Editor } from "@tiptap/core";
+/** Whether the current selection identifies an automatically labelled link. */
+export declare function selectedLinkReference(editor: Editor): import("@tiptap/pm/model").Node | null;
+export declare const isLinkActive: (editor: Editor) => boolean;
 /** A destination supplied by the host application, such as a page or record. */
 export interface LoomaLinkTarget {
     id: string;
@@ -47,6 +50,8 @@ export interface LoomaLinkEditingOptions {
     search: () => LinkSearch | null | undefined;
     resolve: () => LinkResolve | null | undefined;
     baseUrl: () => string;
+    /** Enables automatically labelled references for newly inserted host targets. */
+    references?: () => boolean;
 }
 /**
  * The editor's link form as a state machine: what the form holds, how it applies to the

package/editor/reference-display.d.ts

@@ -0,0 +1,37 @@
+import { Extension, Node, type Editor } from "@tiptap/core";
+import type { Node as ProseMirrorNode } from "@tiptap/pm/model";
+/** Replaceable host-owned presentation, keyed by `link:<id>` or `mention:<id>`. */
+export interface LoomaReferenceDisplay {
+    readonly label: string;
+    readonly href?: string;
+}
+/** Display values indexed by stable target kind and identity, outside authored document data. */
+export type LoomaReferenceMap = Readonly<Record<string, LoomaReferenceDisplay>>;
+/**
+ * Replaces presentation without editing the document or adding an undo/history entry.
+ * @lifecycle Values last until the next replacement or editor destruction; hosts own persistence.
+ */
+export declare function setReferenceDisplay(editor: Editor, references: LoomaReferenceMap): void;
+/**
+ * The current replaceable presentation; absent entries use the saved fallback.
+ * @ownership The returned map belongs to the host; replace it rather than mutating it.
+ */
+export declare function getReferenceDisplay(editor: Editor): LoomaReferenceMap;
+/**
+ * Reads current host presentation, with a durable insertion-time fallback for offline copies.
+ * @failure Unsafe cached destinations fall back to the saved safe URL or no destination.
+ */
+export declare function referenceDisplay(node: ProseMirrorNode, references?: LoomaReferenceMap): LoomaReferenceDisplay;
+/**
+ * An automatically labelled link; custom wording remains an ordinary text link.
+ * @contract Identity and insertion-time fallback stay in JSON; cached presentation stays outside it.
+ */
+export declare const LoomaReference: Node<any, any>;
+/**
+ * Installs metadata-backed node views for references and existing stable-id mentions.
+ * @lifecycle Node views register until destroyed, including across editor reattachment.
+ */
+export declare const LoomaReferencePresentation: Extension<{
+    references: LoomaReferenceMap;
+    mentions: boolean;
+}, any>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@threadlabs/looma",
-  "version": "0.29.15",
+  "version": "0.29.17",
   "type": "module",
   "description": "Looma components as HTML, Vue, and plain DOM, with design tokens.",
   "license": "MIT",