@threadlabs/looma 0.29.14 → 0.29.16

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,16 +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 !== "heading" || node.attrs.level > depth || !node.textContent.trim()) return;
+		if (node.type.name === "loomaTableOfContents") return false;
+		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
@@ -661,7 +664,10 @@ function anchorTransaction(state, previous) {
 	let hasToc = false;
 	const headings = [];
 	state.doc.descendants((node, position) => {
-		if (node.type.name === "loomaTableOfContents") hasToc = true;
+		if (node.type.name === "loomaTableOfContents") {
+			hasToc = true;
+			return false;
+		}
 		if (node.type.name === "heading") headings.push({
 			node,
 			position
@@ -670,6 +676,7 @@ function anchorTransaction(state, previous) {
 	if (!headings.length) return null;
 	const before = /* @__PURE__ */ new Map();
 	previous?.descendants((node) => {
+		if (node.type.name === "loomaTableOfContents") return false;
 		if (node.type.name === "heading" && typeof node.attrs.id === "string") before.set(node.attrs.id, node.textContent.trim());
 	});
 	const custom = (node) => {
@@ -707,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" },
@@ -750,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({
@@ -831,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);
 				}
 			};
@@ -6759,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);
@@ -9929,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 = {
@@ -10770,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":
@@ -486,7 +515,7 @@ function editorDocumentToExpressmark(document, options = {}) {
 	let automaticToc = false;
 	const colors = /* @__PURE__ */ new Set();
 	const urls = /* @__PURE__ */ new Set();
-	const visit = (node) => {
+	const visit = (node, insideToc = false) => {
 		const attrs = node.attrs ?? {};
 		if (node.type === "tableCell" || node.type === "tableHeader") {
 			if (attrs.backgroundColor != null && !colors.has(attrs.backgroundColor)) {
@@ -520,14 +549,14 @@ function editorDocumentToExpressmark(document, options = {}) {
 				urls.add(key);
 			}
 		}
-		if (node.type === "loomaTableOfContents" && !node.content?.length) automaticToc = true;
-		if (node.type === "heading") headings.push({
+		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)
 		});
-		for (const child of node.content ?? []) visit(child);
+		for (const child of node.content ?? []) visit(child, insideToc || node.type === "loomaTableOfContents");
 	};
 	visit(document);
 	const headingIds = /* @__PURE__ */ new WeakMap();
@@ -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.14",
+  "version": "0.29.16",
   "type": "module",
   "description": "Looma components as HTML, Vue, and plain DOM, with design tokens.",
   "license": "MIT",

package/vue/editor/LoomaEditor.d.ts

@@ -8,6 +8,7 @@ import { type LoomaImageUploadDetail } from "../../editor/image-uploads.js";
 import { type LoomaResponder } from "../../editor/requests.js";
 import { type LoomaEditorRangeAction, type LoomaEditorRangeActionDetail, type LoomaEditorSelectionAction, type LoomaEditorSelectionActionDetail } from "../../editor/host-actions.js";
 import { type LoomaLinkTarget } from "../../editor/link-editing.js";
+import { type LoomaReferenceMap } from "../../editor/reference-display.js";
 export type { LoomaImageUploadDetail } from "../../editor/image-uploads.js";
 export type { LoomaRequestInit, LoomaResponder } from "../../editor/requests.js";
 /**
@@ -104,6 +105,11 @@ export declare const LoomaEditor: import("vue").DefineComponent<import("vue").Ex
             text?: string;
         };
     };
+    /** Cached display values; replace this map to refresh labels without editing content. */
+    references: {
+        type: PropType<LoomaReferenceMap | undefined>;
+        default: undefined;
+    };
     editable: {
         type: BooleanConstructor;
         default: boolean;
@@ -249,6 +255,11 @@ export declare const LoomaEditor: import("vue").DefineComponent<import("vue").Ex
             text?: string;
         };
     };
+    /** Cached display values; replace this map to refresh labels without editing content. */
+    references: {
+        type: PropType<LoomaReferenceMap | undefined>;
+        default: undefined;
+    };
     editable: {
         type: BooleanConstructor;
         default: boolean;
@@ -384,6 +395,7 @@ export declare const LoomaEditor: import("vue").DefineComponent<import("vue").Ex
     linkBaseUrl: string;
     disableHighlight: boolean;
     codeLanguages: Readonly<Record<string, import("highlight.js").LanguageFn>> | null;
+    references: Readonly<Record<string, import("@threadlabs/looma/editor").LoomaReferenceDisplay>> | undefined;
     toolbarOpen: boolean;
     slashCommands: LoomaEditorSlashCommands | undefined;
     mentionQuery: LoomaMentionQuery | undefined;

package/vue/editor/index.js

@@ -1832,7 +1832,185 @@ function siteRelativeHref(href, baseUrl) {
 	}
 }
 //#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 } : {}
+	};
+}
+Node$1.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;
+	}
+});
+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
 //#region src/editor/link-editing.ts
+/** Whether the current selection identifies an automatically labelled link. */
+function selectedLinkReference(editor) {
+	const selection = editor.state.selection;
+	return selection instanceof NodeSelection && selection.node.type.name === "loomaReference" ? selection.node : null;
+}
+var isLinkActive = (editor) => editor.isActive("link") || Boolean(selectedLinkReference(editor));
 /** The status line above search results: progress, a hint, or an empty result. */
 function linkFormStatus(state) {
 	if (state.searching) return "Searching…";
@@ -1864,6 +2042,7 @@ function createLinkEditing(options) {
 	let resolveSequence = 0;
 	let currentHref = null;
 	let destroyed = false;
+	let automaticText = false;
 	const set = (patch) => {
 		const previous = state;
 		state = {
@@ -1907,13 +2086,27 @@ function createLinkEditing(options) {
 		}
 		try {
 			const target = await resolve(href);
-			cache.set(href, target);
-			if (sequence === resolveSequence && !destroyed) set({ current: target });
+			if (sequence === resolveSequence && !destroyed) {
+				cache.set(href, target);
+				set({ current: target });
+			}
 		} catch {}
 	};
 	const onTransaction = () => {
-		const href = editor.isActive("link") ? String(editor.getAttributes("link").href ?? "") : null;
-		if (href !== currentHref) {
+		const reference = selectedLinkReference(editor);
+		const display = reference ? referenceDisplay(reference, getReferenceDisplay(editor)) : null;
+		const href = display?.href ?? (editor.isActive("link") ? String(editor.getAttributes("link").href ?? "") : null);
+		if (reference && display && href) {
+			resolveSequence += 1;
+			const target = {
+				id: String(reference.attrs.id),
+				label: display.label,
+				href
+			};
+			cache.set(href, target);
+			if (state.current?.id !== target.id || state.current.label !== target.label || state.current.href !== href) set({ current: target });
+			currentHref = href;
+		} else if (href !== currentHref) {
 			currentHref = href;
 			resolveCurrent(href);
 		}
@@ -1941,6 +2134,30 @@ function createLinkEditing(options) {
 			from: range.from,
 			to: range.to
 		});
+		if (automaticText && state.mode === "target" && state.selected && (options.references?.() || selectedLinkReference(editor))) {
+			const target = state.selected;
+			const previous = editor.state.doc.nodeAt(range.from);
+			const sameTarget = previous?.type.name === "loomaReference" && previous.attrs.id === target.id;
+			chain.insertContent({
+				type: "loomaReference",
+				attrs: {
+					id: target.id,
+					kind: "link",
+					href: sameTarget ? previous.attrs.href : attrs.href,
+					label: sameTarget ? previous.attrs.label : target.label,
+					target: attrs.target
+				}
+			}).setNodeSelection(range.from).run();
+			set({
+				range: {
+					from: range.from,
+					to: range.from + 1,
+					existing: true
+				},
+				error: ""
+			});
+			return true;
+		}
 		if (state.textEditable) {
 			const text = state.text.trim();
 			if (!text) return fail("Enter link text.");
@@ -1988,10 +2205,17 @@ function createLinkEditing(options) {
 		},
 		open(from, to, surface) {
 			const empty = from === to;
-			const existing = editor.isActive("link");
-			const attrs = existing ? editor.getAttributes("link") : {};
+			const reference = selectedLinkReference(editor);
+			const existing = isLinkActive(editor);
+			const attrs = reference?.attrs ?? (existing ? editor.getAttributes("link") : {});
 			const href = typeof attrs.href === "string" ? attrs.href : "";
-			const selected = cache.get(href) ?? null;
+			const display = reference ? referenceDisplay(reference, getReferenceDisplay(editor)) : null;
+			const selected = reference ? {
+				id: String(reference.attrs.id),
+				label: display.label,
+				href: display.href ?? href
+			} : cache.get(href) ?? null;
+			automaticText = Boolean(reference) || empty && !existing;
 			set({
 				surface,
 				range: {
@@ -1999,17 +2223,17 @@ function createLinkEditing(options) {
 					to,
 					existing
 				},
-				textEditable: empty && !existing,
+				textEditable: Boolean(reference) || empty && !existing,
 				href,
 				newTab: attrs.target !== "_self",
-				text: empty && !existing ? "" : editor.state.doc.textBetween(from, to),
+				text: display?.label ?? (empty && !existing ? "" : editor.state.doc.textBetween(from, to)),
 				error: "",
 				selected,
-				mode: options.search() && (!existing || selected) ? "target" : "url",
+				mode: reference || options.search() && (!existing || selected) ? "target" : "url",
 				query: selected?.label ?? href
 			});
 			const resolve = options.resolve();
-			if (existing && resolve && !cache.has(href)) resolve(href).then((target) => {
+			if (existing && !reference && resolve && !cache.has(href)) resolve(href).then((target) => {
 				cache.set(href, target);
 				if (!destroyed && state.href === href && target) set({
 					selected: target,
@@ -2019,7 +2243,7 @@ function createLinkEditing(options) {
 			}).catch(() => {});
 		},
 		setDestination(value) {
-			if (options.search()) {
+			if (options.search() || selectedLinkReference(editor)) {
 				const trimmed = value.trim();
 				const url = /^(https?:\/\/|mailto:|tel:)/i.test(trimmed) || Boolean(state.range?.existing && /^(\/|\.\.?\/|#|\?)/.test(trimmed));
 				set({
@@ -2046,6 +2270,13 @@ function createLinkEditing(options) {
 		},
 		choose(target) {
 			cache.set(target.href, target);
+			if (options.references?.() || selectedLinkReference(editor)) setReferenceDisplay(editor, {
+				...getReferenceDisplay(editor),
+				[`link:${target.id}`]: {
+					label: target.label,
+					href: target.href
+				}
+			});
 			set({
 				selected: target,
 				href: target.href,
@@ -2062,6 +2293,7 @@ function createLinkEditing(options) {
 			apply();
 		},
 		setText(text) {
+			automaticText = false;
 			set({
 				text,
 				error: ""
@@ -2073,6 +2305,15 @@ function createLinkEditing(options) {
 			if (state.surface !== "none") set({ surface: "none" });
 		},
 		remove() {
+			const reference = selectedLinkReference(editor);
+			if (reference) {
+				editor.chain().focus().insertContent({
+					type: "text",
+					text: referenceDisplay(reference, getReferenceDisplay(editor)).label
+				}).run();
+				set({ surface: "none" });
+				return;
+			}
 			if (!editor.isActive("link")) return;
 			editor.chain().focus().extendMarkRange("link").unsetLink().run();
 			if (state.surface === "context") set({ surface: "none" });
@@ -10252,16 +10493,19 @@ function normalizeTableOfContentsConfig$1(attributes) {
 * @contract Depth is a maximum heading level. Relative nesting follows existing
 * ancestors rather than inserting artificial entries for skipped levels.
 */
-function getTableOfContentsEntries$1(doc, depth = 3) {
+function getTableOfContentsEntries$1(doc, depth = 3, references = {}) {
 	const entries = [];
 	const ancestors = [];
 	doc.descendants((node, position) => {
-		if (node.type.name !== "heading" || node.attrs.level > depth || !node.textContent.trim()) return;
+		if (node.type.name === "loomaTableOfContents") return false;
+		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
@@ -10299,7 +10543,10 @@ function anchorTransaction(state, previous) {
 	let hasToc = false;
 	const headings = [];
 	state.doc.descendants((node, position) => {
-		if (node.type.name === "loomaTableOfContents") hasToc = true;
+		if (node.type.name === "loomaTableOfContents") {
+			hasToc = true;
+			return false;
+		}
 		if (node.type.name === "heading") headings.push({
 			node,
 			position
@@ -10308,6 +10555,7 @@ function anchorTransaction(state, previous) {
 	if (!headings.length) return null;
 	const before = /* @__PURE__ */ new Map();
 	previous?.descendants((node) => {
+		if (node.type.name === "loomaTableOfContents") return false;
 		if (node.type.name === "heading" && typeof node.attrs.id === "string") before.set(node.attrs.id, node.textContent.trim());
 	});
 	const custom = (node) => {
@@ -10345,8 +10593,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$1(doc, config.depth));
+function contentsHtml(doc, config, references = {}) {
+	const branches = tableOfContentsTree(getTableOfContentsEntries$1(doc, config.depth, references));
 	const list = (items) => [
 		config.format === "plain" ? "div" : config.format === "numbered" ? "ol" : "ul",
 		{ role: "list" },
@@ -10388,7 +10636,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$1(editor.state.doc).find((heading) => heading.id === id);
+	const entry = getTableOfContentsEntries$1(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({
@@ -10464,7 +10712,7 @@ 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$1(current.attrs)));
+					const { dom: content } = DOMSerializer.renderSpec(document, contentsHtml(editor.state.doc, normalizeTableOfContentsConfig$1(current.attrs), getReferenceDisplay(editor)));
 					dom.replaceChildren(content);
 				}
 			};
@@ -10572,7 +10820,7 @@ var tableOfContentsNodeView = ({ editor, node, getPos }) => {
 			}
 			return;
 		}
-		const found = getTableOfContentsEntries(editor.state.doc, depth);
+		const found = getTableOfContentsEntries(editor.state.doc, depth, getReferenceDisplay(editor));
 		const signature = JSON.stringify([format, found.map(({ id: entryId, text, level }) => [
 			entryId,
 			text,
@@ -13563,6 +13811,11 @@ var LoomaEditor = defineComponent({
 			type: Object,
 			default: () => ({ ...EMPTY_DOCUMENT })
 		},
+		/** Cached display values; replace this map to refresh labels without editing content. */
+		references: {
+			type: Object,
+			default: void 0
+		},
 		editable: {
 			type: Boolean,
 			default: true
@@ -13936,6 +14189,7 @@ var LoomaEditor = defineComponent({
 			session = createEditorSession({
 				extensions: [
 					...getDefaultEditorExtensions({
+						references: props.references,
 						placeholder: props.placeholder,
 						linkBaseUrl: props.linkBaseUrl,
 						mention: consumerMention ? false : mentionExtension,
@@ -13978,7 +14232,7 @@ var LoomaEditor = defineComponent({
 							if (view.isDestroyed) return;
 							editorStateVersion.value += 1;
 							const instance = editor.value;
-							if (instance?.isFocused && instance.state.selection.empty && instance.isActive("link") && linkState.value.surface !== "popover") {
+							if (instance?.isFocused && (instance.state.selection.empty || selectedLinkReference(instance)) && isLinkActive(instance) && linkState.value.surface !== "popover") {
 								linkPopup?.setAnchor(() => link.getBoundingClientRect());
 								linkPopup?.show();
 							}
@@ -14017,7 +14271,8 @@ var LoomaEditor = defineComponent({
 				editor: session.editor,
 				search: () => answers("link-search") ? async (query) => await askLatest("link-search", { query }) ?? [] : null,
 				resolve: () => async (href) => await askLatest("link-resolve", { href }),
-				baseUrl: () => props.linkBaseUrl
+				baseUrl: () => props.linkBaseUrl,
+				references: () => props.references !== void 0
 			});
 			engine.subscribe(() => {
 				linkState.value = engine.state;
@@ -14214,6 +14469,9 @@ var LoomaEditor = defineComponent({
 			const wasFocused = instance.isFocused;
 			if (session.setContent(value, lastFocusedSelection) && wasFocused) rememberSelection(instance);
 		}, { deep: true });
+		watch(() => props.references, (value) => {
+			if (editor.value) setReferenceDisplay(editor.value, value ?? {});
+		}, { deep: true });
 		const closeTableUi = () => {
 			Object.assign(tableUi, LOOMA_TABLE_CONTROLS_CLOSED);
 			tableUi.menuOpen = false;
@@ -14430,7 +14688,7 @@ var LoomaEditor = defineComponent({
 			editor: instance,
 			element,
 			pluginKey: "looma-link-context-menu",
-			shouldShow: ({ editor: menuEditor, from, to }) => from === to && menuEditor.isActive("link") && linkState.value.surface !== "popover" && !formatting?.dismissed(menuEditor.state.selection) && Boolean(menuEditor.isFocused || linkState.value.surface === "context" || linkPopup?.element.contains(document.activeElement)) && !(props.toolbarMode === "contextual" && floatingFormattingMode() && formattingActive()),
+			shouldShow: ({ editor: menuEditor, from, to }) => (from === to || Boolean(selectedLinkReference(menuEditor))) && isLinkActive(menuEditor) && linkState.value.surface !== "popover" && !formatting?.dismissed(menuEditor.state.selection) && Boolean(menuEditor.isFocused || linkState.value.surface === "context" || linkPopup?.element.contains(document.activeElement)) && !(props.toolbarMode === "contextual" && floatingFormattingMode() && formattingActive()),
 			maxWidth: () => Math.min(480, window.innerWidth - 24),
 			related: editorRoot,
 			onDismiss: (reason) => reason === "escape" ? dismissFormatting() : linkPopup?.hide()
@@ -14795,8 +15053,8 @@ var LoomaEditor = defineComponent({
 				size: "sm",
 				variant: "ghost",
 				"aria-expanded": linkState.value.surface === "popover" ? "true" : "false",
-				"aria-pressed": instance.isActive("link") ? "true" : "false",
-				"data-active": instance.isActive("link") ? "true" : "false",
+				"aria-pressed": isLinkActive(instance) ? "true" : "false",
+				"data-active": isLinkActive(instance) ? "true" : "false",
 				onPointerenter: () => showTool(linkTriggerId, "Link", false),
 				onPointerleave: hideTool,
 				onPointerdown: (event) => {
@@ -14978,7 +15236,7 @@ var LoomaEditor = defineComponent({
 					ref: formattingSurfaceRef,
 					class: "looma-editor__floating-shell looma-editor__formatting-shell",
 					hidden: true
-				}, [props.toolbarMode === "contextual" ? h(Stack, { gap: "xs" }, () => [renderToolbar(instance, true), (linkState.value.surface === "context" || instance.state.selection.empty && instance.isActive("link")) && linkState.value.surface !== "popover" && formattingActive() ? renderLinkContextCard(instance) : null]) : renderToolbar(instance, true, props.toolbarMode === "popover")])]) : null,
+				}, [props.toolbarMode === "contextual" ? h(Stack, { gap: "xs" }, () => [renderToolbar(instance, true), (linkState.value.surface === "context" || (instance.state.selection.empty || selectedLinkReference(instance)) && isLinkActive(instance)) && linkState.value.surface !== "popover" && formattingActive() ? renderLinkContextCard(instance) : null]) : renderToolbar(instance, true, props.toolbarMode === "popover")])]) : null,
 				instance && props.editable ? h("div", { key: "looma-link-host" }, [h("div", {
 					ref: linkSurfaceRef,
 					class: "looma-editor__floating-shell looma-editor__link-shell",