@ecsplico/editor 2.1.1 → 3.0.0

package/dist/features/composites/reference-ai.js

@@ -0,0 +1,16 @@
+//#region src/features/composites/reference-ai.ts
+/**
+* How the chat and rewrite models learn the `reference` chip: written as Markdown text `[@<Block-ID>]`, which the
+* composites feature's `normalize` stage turns back into a chip. Not a convert target (no conversion provider owns it).
+*/
+const REFERENCE_AI_BLOCK = {
+	id: "reference",
+	label: "Verweis",
+	description: "Inline-Verweis auf einen Baustein dieses Dokuments (Zitat, Quelle), optional mit Fundstelle (Seite oder Zeit).",
+	syntax: "[@<Block-ID>] oder [@<Block-ID>, S. 12]",
+	example: "Das zeigt die Studie [@0f3c9a52-7d1e-4b8a-9c2f-5e6d7a8b9c0d, S. 12]."
+};
+//#endregion
+export { REFERENCE_AI_BLOCK };
+
+//# sourceMappingURL=reference-ai.js.map

package/dist/features/composites/reference-ai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-ai.js","names":[],"sources":["../../../src/features/composites/reference-ai.ts"],"sourcesContent":["// i18n-ignore-file: model-facing block description (German prompt text, not UI)\nimport type { AiBlock } from '../../core/feature'\n\n/**\n * How the chat and rewrite models learn the `reference` chip: written as Markdown text `[@<Block-ID>]`, which the\n * composites feature's `normalize` stage turns back into a chip. Not a convert target (no conversion provider owns it).\n */\nexport const REFERENCE_AI_BLOCK: AiBlock = {\n  id: 'reference',\n  label: 'Verweis',\n  description: 'Inline-Verweis auf einen Baustein dieses Dokuments (Zitat, Quelle), optional mit Fundstelle (Seite oder Zeit).',\n  syntax: '[@<Block-ID>] oder [@<Block-ID>, S. 12]',\n  example: 'Das zeigt die Studie [@0f3c9a52-7d1e-4b8a-9c2f-5e6d7a8b9c0d, S. 12].',\n}\n"],"mappings":";;;;;AAOA,MAAa,qBAA8B;CACzC,IAAI;CACJ,OAAO;CACP,aAAa;CACb,QAAQ;CACR,SAAS;AACX"}

package/dist/features/composites/reference-label.d.ts

@@ -0,0 +1,19 @@
+import { CompositeKind } from "./kinds.js";
+import "./reference.js";
+import { Editor } from "@tiptap/core";
+import { Node as Node$1 } from "@tiptap/pm/model";
+//#region src/features/composites/reference-label.d.ts
+/** What a reference chip shows of its target: the parts of a `CompositeRow`, or of a composite node (`referenceTarget`). */
+export interface ReferenceTarget {
+  meta: Record<string, unknown>;
+  title: string;
+  kindLabel: string;
+}
+/** The Baustein `node` as a reference target. */
+export declare function referenceTarget(node: Node$1, kinds: readonly CompositeKind[]): ReferenceTarget;
+/** The chip text: the short citation ("Doe et al. 2024") when the target has bibliographic data, else its title, else its kind's label. */
+export declare function referenceLabel(target: ReferenceTarget): string;
+/** The chip's tooltip: the full citation, else the title. */
+export declare function referenceTitle(target: ReferenceTarget): string;
+//#endregion
+//# sourceMappingURL=reference-label.d.ts.map

package/dist/features/composites/reference-label.js

@@ -0,0 +1,58 @@
+import { findBlockById } from "../../core/schema/block-ids.js";
+import { compositeKind } from "./kinds.js";
+import "./meta-keys.js";
+import { compositeKindsOf } from "./nodes.js";
+import { citeFull, citeShort } from "./bibliography.js";
+//#region src/features/composites/reference-label.ts
+/** The Baustein `node` as a reference target. */
+function referenceTarget(node, kinds) {
+	return {
+		meta: node.attrs.meta ?? {},
+		title: node.childCount > 0 ? node.child(0).textContent.trim() : "",
+		kindLabel: compositeKind(kinds, String(node.attrs.kind)).label
+	};
+}
+const bibOfTarget = (target) => {
+	const bib = target.meta["bib"];
+	if (!bib || typeof bib !== "object" || Array.isArray(bib)) return null;
+	return "type" in bib && typeof bib.type === "string" ? bib : null;
+};
+/** The chip text: the short citation ("Doe et al. 2024") when the target has bibliographic data, else its title, else its kind's label. */
+function referenceLabel(target) {
+	const bib = bibOfTarget(target);
+	return bib ? citeShort(bib, target.title) : target.title || target.kindLabel;
+}
+/** The chip's tooltip: the full citation, else the title. */
+function referenceTitle(target) {
+	const bib = bibOfTarget(target);
+	return bib ? citeFull({
+		...bib,
+		title: target.title
+	}) : target.title || target.kindLabel;
+}
+/** The attrs of a `reference` node that the label needs, typed (a node's `attrs` is a loose record). */
+function referenceAttrsOf(node) {
+	return {
+		target: String(node.attrs.target ?? ""),
+		label: String(node.attrs.label ?? "")
+	};
+}
+/** What a chip shows now: the live label and tooltip of its target, or (`gone`) the attrs' cached label when the target no longer exists. */
+function resolveReference(editor, attrs) {
+	const found = findBlockById(editor.state.doc, attrs.target);
+	if (found?.node.type.name !== "composite") return {
+		label: attrs.label,
+		title: attrs.label,
+		gone: true
+	};
+	const target = referenceTarget(found.node, compositeKindsOf(editor));
+	return {
+		label: referenceLabel(target),
+		title: referenceTitle(target),
+		gone: false
+	};
+}
+//#endregion
+export { referenceAttrsOf, referenceLabel, referenceTarget, referenceTitle, resolveReference };
+
+//# sourceMappingURL=reference-label.js.map

package/dist/features/composites/reference-label.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-label.js","names":[],"sources":["../../../src/features/composites/reference-label.ts"],"sourcesContent":["import type { Editor } from '@tiptap/core'\nimport type { Node as PMNode } from '@tiptap/pm/model'\nimport { findBlockById } from '../../core/schema'\nimport { type CslItem, BIB_KEY, citeFull, citeShort } from './bibliography'\nimport { compositeKind, type CompositeKind } from './kinds'\nimport { compositeKindsOf } from './nodes'\nimport type { ReferenceAttrs } from './reference'\n\n/** What a reference chip shows of its target: the parts of a `CompositeRow`, or of a composite node (`referenceTarget`). */\nexport interface ReferenceTarget {\n  meta: Record<string, unknown>\n  title: string\n  kindLabel: string\n}\n\n/** The Baustein `node` as a reference target. */\nexport function referenceTarget(node: PMNode, kinds: readonly CompositeKind[]): ReferenceTarget {\n  return {\n    meta: (node.attrs.meta ?? {}) as Record<string, unknown>,\n    title: node.childCount > 0 ? node.child(0).textContent.trim() : '',\n    kindLabel: compositeKind(kinds, String(node.attrs.kind)).label,\n  }\n}\n\nconst bibOfTarget = (target: ReferenceTarget): CslItem | null => {\n  const bib = target.meta[BIB_KEY]\n  if (!bib || typeof bib !== 'object' || Array.isArray(bib)) return null\n  return 'type' in bib && typeof bib.type === 'string' ? bib as CslItem : null\n}\n\n/** The chip text: the short citation (\"Doe et al. 2024\") when the target has bibliographic data, else its title, else its kind's label. */\nexport function referenceLabel(target: ReferenceTarget): string {\n  const bib = bibOfTarget(target)\n  return bib ? citeShort(bib, target.title) : target.title || target.kindLabel\n}\n\n/** The chip's tooltip: the full citation, else the title. */\nexport function referenceTitle(target: ReferenceTarget): string {\n  const bib = bibOfTarget(target)\n  return bib ? citeFull({ ...bib, title: target.title }) : target.title || target.kindLabel\n}\n\n/** The attrs of a `reference` node that the label needs, typed (a node's `attrs` is a loose record). */\nexport function referenceAttrsOf(node: PMNode): Pick<ReferenceAttrs, 'target' | 'label'> {\n  return { target: String(node.attrs.target ?? ''), label: String(node.attrs.label ?? '') }\n}\n\n/** What a chip shows now: the live label and tooltip of its target, or (`gone`) the attrs' cached label when the target no longer exists. */\nexport function resolveReference(editor: Editor, attrs: Pick<ReferenceAttrs, 'target' | 'label'>): { label: string, title: string, gone: boolean } {\n  const found = findBlockById(editor.state.doc, attrs.target)\n  if (found?.node.type.name !== 'composite') return { label: attrs.label, title: attrs.label, gone: true }\n  const target = referenceTarget(found.node, compositeKindsOf(editor))\n  return { label: referenceLabel(target), title: referenceTitle(target), gone: false }\n}\n"],"mappings":";;;;;;;AAgBA,SAAgB,gBAAgB,MAAc,OAAkD;CAC9F,OAAO;EACL,MAAO,KAAK,MAAM,QAAQ,CAAC;EAC3B,OAAO,KAAK,aAAa,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,YAAY,KAAK,IAAI;EAChE,WAAW,cAAc,OAAO,OAAO,KAAK,MAAM,IAAI,CAAC,CAAC,CAAC;CAC3D;AACF;AAEA,MAAM,eAAe,WAA4C;CAC/D,MAAM,MAAM,OAAO,KAAA;CACnB,IAAI,CAAC,OAAO,OAAO,QAAQ,YAAY,MAAM,QAAQ,GAAG,GAAG,OAAO;CAClE,OAAO,UAAU,OAAO,OAAO,IAAI,SAAS,WAAW,MAAiB;AAC1E;;AAGA,SAAgB,eAAe,QAAiC;CAC9D,MAAM,MAAM,YAAY,MAAM;CAC9B,OAAO,MAAM,UAAU,KAAK,OAAO,KAAK,IAAI,OAAO,SAAS,OAAO;AACrE;;AAGA,SAAgB,eAAe,QAAiC;CAC9D,MAAM,MAAM,YAAY,MAAM;CAC9B,OAAO,MAAM,SAAS;EAAE,GAAG;EAAK,OAAO,OAAO;CAAM,CAAC,IAAI,OAAO,SAAS,OAAO;AAClF;;AAGA,SAAgB,iBAAiB,MAAwD;CACvF,OAAO;EAAE,QAAQ,OAAO,KAAK,MAAM,UAAU,EAAE;EAAG,OAAO,OAAO,KAAK,MAAM,SAAS,EAAE;CAAE;AAC1F;;AAGA,SAAgB,iBAAiB,QAAgB,OAAkG;CACjJ,MAAM,QAAQ,cAAc,OAAO,MAAM,KAAK,MAAM,MAAM;CAC1D,IAAI,OAAO,KAAK,KAAK,SAAS,aAAa,OAAO;EAAE,OAAO,MAAM;EAAO,OAAO,MAAM;EAAO,MAAM;CAAK;CACvG,MAAM,SAAS,gBAAgB,MAAM,MAAM,iBAAiB,MAAM,CAAC;CACnE,OAAO;EAAE,OAAO,eAAe,MAAM;EAAG,OAAO,eAAe,MAAM;EAAG,MAAM;CAAM;AACrF"}

package/dist/features/composites/reference-suggestion.d.ts

@@ -0,0 +1,10 @@
+import { Translate } from "../../i18n/index.js";
+import { ReferenceOptions } from "./reference.js";
+//#region src/features/composites/reference-suggestion.d.ts
+/**
+ * `[@` trigger for ReferenceNode: the Bausteine of the document (with a block ID) whose title, kind or chip label (the
+ * short citation) contains the typed query, inserted as a chip that shows the short citation or the title. `t` renders the popup texts in the app's language.
+ */
+export declare const referenceSuggestion: (t: Translate) => NonNullable<ReferenceOptions["suggestion"]>;
+//#endregion
+//# sourceMappingURL=reference-suggestion.d.ts.map

package/dist/features/composites/reference-suggestion.js

@@ -0,0 +1,41 @@
+import { ABILITY } from "../../core/schema/abilities.js";
+import { hasAbility } from "../../core/abilities.js";
+import { createSuggestionRender } from "../../core/suggestion-popup.js";
+import { compositeKindsOf } from "./nodes.js";
+import { referenceLabel } from "./reference-label.js";
+import { compositeRows } from "./rows.js";
+//#region src/features/composites/reference-suggestion.ts
+/** Rows of the popup; more would need scrolling past what a citation picker is for, and the query narrows them anyway. */
+const MAX_ITEMS = 20;
+/**
+* `[@` trigger for ReferenceNode: the Bausteine of the document (with a block ID) whose title, kind or chip label (the
+* short citation) contains the typed query, inserted as a chip that shows the short citation or the title. `t` renders the popup texts in the app's language.
+*/
+const referenceSuggestion = (t) => ({
+	allow: ({ editor }) => hasAbility(editor, ABILITY.reference),
+	items: ({ query, editor }) => {
+		const needle = query.trim().toLowerCase();
+		return compositeRows(editor.state.doc, compositeKindsOf(editor)).rows.filter((row) => row.id !== null).map((row) => ({
+			row,
+			label: referenceLabel(row)
+		})).filter(({ row, label }) => !needle || [
+			label,
+			row.title,
+			row.kindLabel
+		].some((part) => part.toLowerCase().includes(needle))).slice(0, MAX_ITEMS).map(({ row, label }) => ({
+			target: row.id,
+			documentId: null,
+			locator: null,
+			label
+		}));
+	},
+	render: createSuggestionRender({
+		display: (item) => ({ label: item.label }),
+		emptyText: t("composites.reference.empty"),
+		loadingText: t("common.loading")
+	})
+});
+//#endregion
+export { referenceSuggestion };
+
+//# sourceMappingURL=reference-suggestion.js.map

package/dist/features/composites/reference-suggestion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-suggestion.js","names":[],"sources":["../../../src/features/composites/reference-suggestion.ts"],"sourcesContent":["import { createSuggestionRender, hasAbility } from '../../core'\nimport { ABILITY } from '../../core/schema'\nimport type { Translate } from '../../i18n'\nimport { compositeKindsOf } from './nodes'\nimport type { ReferenceAttrs, ReferenceOptions } from './reference'\nimport { referenceLabel } from './reference-label'\nimport { compositeRows } from './rows'\n\n/** Rows of the popup; more would need scrolling past what a citation picker is for, and the query narrows them anyway. */\nconst MAX_ITEMS = 20\n\n/**\n * `[@` trigger for ReferenceNode: the Bausteine of the document (with a block ID) whose title, kind or chip label (the\n * short citation) contains the typed query, inserted as a chip that shows the short citation or the title. `t` renders the popup texts in the app's language.\n */\nexport const referenceSuggestion = (t: Translate): NonNullable<ReferenceOptions['suggestion']> => ({\n  allow: ({ editor }) => hasAbility(editor, ABILITY.reference),\n  items: ({ query, editor }): ReferenceAttrs[] => {\n    const needle = query.trim().toLowerCase()\n    return compositeRows(editor.state.doc, compositeKindsOf(editor)).rows\n      .filter(row => row.id !== null)\n      .map(row => ({ row, label: referenceLabel(row) }))\n      .filter(({ row, label }) => !needle || [label, row.title, row.kindLabel].some(part => part.toLowerCase().includes(needle)))\n      .slice(0, MAX_ITEMS)\n      .map(({ row, label }): ReferenceAttrs => ({ target: row.id!, documentId: null, locator: null, label }))\n  },\n  render: createSuggestionRender<ReferenceAttrs>({\n    display: item => ({ label: item.label }),\n    emptyText: t('composites.reference.empty'),\n    loadingText: t('common.loading'),\n  }),\n})\n"],"mappings":";;;;;;;;AASA,MAAM,YAAY;;;;;AAMlB,MAAa,uBAAuB,OAA+D;CACjG,QAAQ,EAAE,aAAa,WAAW,QAAQ,QAAQ,SAAS;CAC3D,QAAQ,EAAE,OAAO,aAA+B;EAC9C,MAAM,SAAS,MAAM,KAAK,CAAC,CAAC,YAAY;EACxC,OAAO,cAAc,OAAO,MAAM,KAAK,iBAAiB,MAAM,CAAC,CAAC,CAAC,KAC9D,QAAO,QAAO,IAAI,OAAO,IAAI,CAAC,CAC9B,KAAI,SAAQ;GAAE;GAAK,OAAO,eAAe,GAAG;EAAE,EAAE,CAAC,CACjD,QAAQ,EAAE,KAAK,YAAY,CAAC,UAAU;GAAC;GAAO,IAAI;GAAO,IAAI;EAAS,CAAC,CAAC,MAAK,SAAQ,KAAK,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,CAAC,CAAC,CAC1H,MAAM,GAAG,SAAS,CAAC,CACnB,KAAK,EAAE,KAAK,aAA6B;GAAE,QAAQ,IAAI;GAAK,YAAY;GAAM,SAAS;GAAM;EAAM,EAAE;CAC1G;CACA,QAAQ,uBAAuC;EAC7C,UAAS,UAAS,EAAE,OAAO,KAAK,MAAM;EACtC,WAAW,EAAE,4BAA4B;EACzC,aAAa,EAAE,gBAAgB;CACjC,CAAC;AACH"}

package/dist/features/composites/reference-text.d.ts

@@ -0,0 +1,18 @@
+import { JSONContent } from "@tiptap/core";
+import { Node as Node$1 } from "@tiptap/pm/model";
+//#region src/features/composites/reference-text.d.ts
+/** Block IDs of every composite in a TipTap JSON tree, added to `into`. */
+export declare function collectCompositeIds(content: JSONContent | null | undefined, into: Set<string>): Set<string>;
+/**
+ * Turns `[@<id>]` / `[@<id>, <locator>]` tokens in text nodes into `reference` nodes (attrs target, locator, empty
+ * `label`: the node view resolves the live label) — for imported and AI-generated Markdown, whose parser keeps the
+ * token as text. Only ids in `ids` (the Bausteine of the document) match; unknown ids and text in code blocks, inline
+ * code or links stay plain. Returns the input unchanged when nothing matched.
+ */
+export declare function referencesFromText(json: JSONContent, ids: ReadonlySet<string>): JSONContent;
+/** Block IDs of the composites of `doc`: the Bausteine a `[@id]` text may point at. */
+export declare function compositeIdsOf(doc: Node$1): Set<string>;
+/** The `normalize` stage: the composites of the document (`current`) and of `blocks` themselves may be referenced by text. */
+export declare function normalizeReferences(blocks: JSONContent[], current: ReadonlySet<string>): JSONContent[];
+//#endregion
+//# sourceMappingURL=reference-text.d.ts.map

package/dist/features/composites/reference-text.js

@@ -0,0 +1,89 @@
+import { blockIdOf } from "../../core/schema/block-ids.js";
+import { REFERENCE_TOKEN_SOURCE } from "./reference.js";
+//#region src/features/composites/reference-text.ts
+/** `[@<block id>]` or `[@<block id>, <locator>]`; a `]` inside the locator is written `\]`. */
+const TOKEN = new RegExp(REFERENCE_TOKEN_SOURCE, "g");
+/** Block IDs of every composite in a TipTap JSON tree, added to `into`. */
+function collectCompositeIds(content, into) {
+	if (!content) return into;
+	if (content.type === "composite" && typeof content.attrs?.id === "string" && content.attrs.id) into.add(content.attrs.id);
+	for (const child of content.content ?? []) collectCompositeIds(child, into);
+	return into;
+}
+/**
+* Turns `[@<id>]` / `[@<id>, <locator>]` tokens in text nodes into `reference` nodes (attrs target, locator, empty
+* `label`: the node view resolves the live label) — for imported and AI-generated Markdown, whose parser keeps the
+* token as text. Only ids in `ids` (the Bausteine of the document) match; unknown ids and text in code blocks, inline
+* code or links stay plain. Returns the input unchanged when nothing matched.
+*/
+function referencesFromText(json, ids) {
+	if (!ids.size) return json;
+	const splitText = (node) => {
+		const text = node.text ?? "";
+		if (!text.includes("[@") || node.marks?.some((m) => m.type === "code" || m.type === "link")) return [node];
+		const out = [];
+		let last = 0;
+		for (const match of text.matchAll(TOKEN)) {
+			const target = match[1];
+			if (!ids.has(target)) continue;
+			const at = match.index ?? 0;
+			if (at > last) out.push({
+				...node,
+				text: text.slice(last, at)
+			});
+			out.push({
+				type: "reference",
+				attrs: {
+					target,
+					documentId: null,
+					locator: match[2]?.replace(/\\\]/g, "]").trim() || null,
+					label: ""
+				},
+				...node.marks?.length ? { marks: node.marks } : {}
+			});
+			last = at + match[0].length;
+		}
+		if (!out.length) return [node];
+		if (last < text.length) out.push({
+			...node,
+			text: text.slice(last)
+		});
+		return out;
+	};
+	const walk = (node) => {
+		if (!node.content || node.type === "codeBlock") return node;
+		let changed = false;
+		const content = node.content.flatMap((child) => {
+			const next = child.type === "text" ? splitText(child) : [walk(child)];
+			if (next.length !== 1 || next[0] !== child) changed = true;
+			return next;
+		});
+		return changed ? {
+			...node,
+			content
+		} : node;
+	};
+	return walk(json);
+}
+/** Block IDs of the composites of `doc`: the Bausteine a `[@id]` text may point at. */
+function compositeIdsOf(doc) {
+	const ids = /* @__PURE__ */ new Set();
+	doc.descendants((node) => {
+		if (node.type.name !== "composite") return;
+		const id = blockIdOf(node);
+		if (id) ids.add(id);
+	});
+	return ids;
+}
+/** The `normalize` stage: the composites of the document (`current`) and of `blocks` themselves may be referenced by text. */
+function normalizeReferences(blocks, current) {
+	const doc = {
+		type: "doc",
+		content: blocks
+	};
+	return referencesFromText(doc, collectCompositeIds(doc, new Set(current))).content ?? [];
+}
+//#endregion
+export { collectCompositeIds, compositeIdsOf, normalizeReferences, referencesFromText };
+
+//# sourceMappingURL=reference-text.js.map

package/dist/features/composites/reference-text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-text.js","names":[],"sources":["../../../src/features/composites/reference-text.ts"],"sourcesContent":["import type { JSONContent } from '@tiptap/core'\nimport type { Node as PMNode } from '@tiptap/pm/model'\nimport { blockIdOf } from '../../core/schema'\nimport { REFERENCE_TOKEN_SOURCE } from './reference'\n\n/** `[@<block id>]` or `[@<block id>, <locator>]`; a `]` inside the locator is written `\\]`. */\nconst TOKEN = new RegExp(REFERENCE_TOKEN_SOURCE, 'g')\n\n/** Block IDs of every composite in a TipTap JSON tree, added to `into`. */\nexport function collectCompositeIds(content: JSONContent | null | undefined, into: Set<string>): Set<string> {\n  if (!content) return into\n  if (content.type === 'composite' && typeof content.attrs?.id === 'string' && content.attrs.id) into.add(content.attrs.id)\n  for (const child of content.content ?? []) collectCompositeIds(child, into)\n  return into\n}\n\n/**\n * Turns `[@<id>]` / `[@<id>, <locator>]` tokens in text nodes into `reference` nodes (attrs target, locator, empty\n * `label`: the node view resolves the live label) — for imported and AI-generated Markdown, whose parser keeps the\n * token as text. Only ids in `ids` (the Bausteine of the document) match; unknown ids and text in code blocks, inline\n * code or links stay plain. Returns the input unchanged when nothing matched.\n */\nexport function referencesFromText(json: JSONContent, ids: ReadonlySet<string>): JSONContent {\n  if (!ids.size) return json\n\n  const splitText = (node: JSONContent): JSONContent[] => {\n    const text = node.text ?? ''\n    if (!text.includes('[@') || node.marks?.some(m => m.type === 'code' || m.type === 'link')) return [node]\n    const out: JSONContent[] = []\n    let last = 0\n    for (const match of text.matchAll(TOKEN)) {\n      const target = match[1]!\n      if (!ids.has(target)) continue\n      const at = match.index ?? 0\n      if (at > last) out.push({ ...node, text: text.slice(last, at) })\n      out.push({\n        type: 'reference',\n        attrs: { target, documentId: null, locator: match[2]?.replace(/\\\\\\]/g, ']').trim() || null, label: '' },\n        ...(node.marks?.length ? { marks: node.marks } : {}),\n      })\n      last = at + match[0].length\n    }\n    if (!out.length) return [node]\n    if (last < text.length) out.push({ ...node, text: text.slice(last) })\n    return out\n  }\n\n  const walk = (node: JSONContent): JSONContent => {\n    if (!node.content || node.type === 'codeBlock') return node\n    let changed = false\n    const content = node.content.flatMap((child) => {\n      const next = child.type === 'text' ? splitText(child) : [walk(child)]\n      if (next.length !== 1 || next[0] !== child) changed = true\n      return next\n    })\n    return changed ? { ...node, content } : node\n  }\n  return walk(json)\n}\n\n/** Block IDs of the composites of `doc`: the Bausteine a `[@id]` text may point at. */\nexport function compositeIdsOf(doc: PMNode): Set<string> {\n  const ids = new Set<string>()\n  doc.descendants((node) => {\n    if (node.type.name !== 'composite') return\n    const id = blockIdOf(node)\n    if (id) ids.add(id)\n  })\n  return ids\n}\n\n/** The `normalize` stage: the composites of the document (`current`) and of `blocks` themselves may be referenced by text. */\nexport function normalizeReferences(blocks: JSONContent[], current: ReadonlySet<string>): JSONContent[] {\n  const doc: JSONContent = { type: 'doc', content: blocks }\n  return referencesFromText(doc, collectCompositeIds(doc, new Set(current))).content ?? []\n}\n"],"mappings":";;;;AAMA,MAAM,QAAQ,IAAI,OAAO,wBAAwB,GAAG;;AAGpD,SAAgB,oBAAoB,SAAyC,MAAgC;CAC3G,IAAI,CAAC,SAAS,OAAO;CACrB,IAAI,QAAQ,SAAS,eAAe,OAAO,QAAQ,OAAO,OAAO,YAAY,QAAQ,MAAM,IAAI,KAAK,IAAI,QAAQ,MAAM,EAAE;CACxH,KAAK,MAAM,SAAS,QAAQ,WAAW,CAAC,GAAG,oBAAoB,OAAO,IAAI;CAC1E,OAAO;AACT;;;;;;;AAQA,SAAgB,mBAAmB,MAAmB,KAAuC;CAC3F,IAAI,CAAC,IAAI,MAAM,OAAO;CAEtB,MAAM,aAAa,SAAqC;EACtD,MAAM,OAAO,KAAK,QAAQ;EAC1B,IAAI,CAAC,KAAK,SAAS,IAAI,KAAK,KAAK,OAAO,MAAK,MAAK,EAAE,SAAS,UAAU,EAAE,SAAS,MAAM,GAAG,OAAO,CAAC,IAAI;EACvG,MAAM,MAAqB,CAAC;EAC5B,IAAI,OAAO;EACX,KAAK,MAAM,SAAS,KAAK,SAAS,KAAK,GAAG;GACxC,MAAM,SAAS,MAAM;GACrB,IAAI,CAAC,IAAI,IAAI,MAAM,GAAG;GACtB,MAAM,KAAK,MAAM,SAAS;GAC1B,IAAI,KAAK,MAAM,IAAI,KAAK;IAAE,GAAG;IAAM,MAAM,KAAK,MAAM,MAAM,EAAE;GAAE,CAAC;GAC/D,IAAI,KAAK;IACP,MAAM;IACN,OAAO;KAAE;KAAQ,YAAY;KAAM,SAAS,MAAM,EAAE,EAAE,QAAQ,SAAS,GAAG,CAAC,CAAC,KAAK,KAAK;KAAM,OAAO;IAAG;IACtG,GAAI,KAAK,OAAO,SAAS,EAAE,OAAO,KAAK,MAAM,IAAI,CAAC;GACpD,CAAC;GACD,OAAO,KAAK,MAAM,EAAE,CAAC;EACvB;EACA,IAAI,CAAC,IAAI,QAAQ,OAAO,CAAC,IAAI;EAC7B,IAAI,OAAO,KAAK,QAAQ,IAAI,KAAK;GAAE,GAAG;GAAM,MAAM,KAAK,MAAM,IAAI;EAAE,CAAC;EACpE,OAAO;CACT;CAEA,MAAM,QAAQ,SAAmC;EAC/C,IAAI,CAAC,KAAK,WAAW,KAAK,SAAS,aAAa,OAAO;EACvD,IAAI,UAAU;EACd,MAAM,UAAU,KAAK,QAAQ,SAAS,UAAU;GAC9C,MAAM,OAAO,MAAM,SAAS,SAAS,UAAU,KAAK,IAAI,CAAC,KAAK,KAAK,CAAC;GACpE,IAAI,KAAK,WAAW,KAAK,KAAK,OAAO,OAAO,UAAU;GACtD,OAAO;EACT,CAAC;EACD,OAAO,UAAU;GAAE,GAAG;GAAM;EAAQ,IAAI;CAC1C;CACA,OAAO,KAAK,IAAI;AAClB;;AAGA,SAAgB,eAAe,KAA0B;CACvD,MAAM,sBAAM,IAAI,IAAY;CAC5B,IAAI,aAAa,SAAS;EACxB,IAAI,KAAK,KAAK,SAAS,aAAa;EACpC,MAAM,KAAK,UAAU,IAAI;EACzB,IAAI,IAAI,IAAI,IAAI,EAAE;CACpB,CAAC;CACD,OAAO;AACT;;AAGA,SAAgB,oBAAoB,QAAuB,SAA6C;CACtG,MAAM,MAAmB;EAAE,MAAM;EAAO,SAAS;CAAO;CACxD,OAAO,mBAAmB,KAAK,oBAAoB,KAAK,IAAI,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC;AACzF"}

package/dist/features/composites/reference.d.ts

@@ -0,0 +1,44 @@
+import { Extension, Node } from "@tiptap/core";
+import { PluginKey } from "@tiptap/pm/state";
+import { SuggestionOptions } from "@tiptap/suggestion";
+//#region src/features/composites/reference.d.ts
+/**
+ * Attributes of a reference chip. `target` is the block ID of the referenced Baustein; `label` caches its display text
+ * for the cases the target cannot be resolved (the node view shows the live label and only falls back to this one).
+ */
+export interface ReferenceAttrs {
+  target: string;
+  /** Document of the target; `null` = this document (cross-document references are not resolved yet). */
+  documentId: string | null;
+  /** Position inside the target's source: `S. 12` (PDF page), `03:14` (recording time); `null` = the whole Baustein. */
+  locator: string | null;
+  label: string;
+}
+export declare const REFERENCE_NODE = "reference";
+/** `[@<target>]` / `[@<target>, <locator>]`, the chip's Markdown form; `]` in a locator is escaped as `\]`. */
+export declare function referenceMarkdown(attrs: Pick<ReferenceAttrs, 'target' | 'locator'>): string;
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    reference: {
+      /** Inserts a reference chip (followed by a space) at the selection. */
+      insertReference: (attrs: Partial<ReferenceAttrs> & Pick<ReferenceAttrs, 'target'>) => ReturnType;
+      /** Sets the locator of the reference chip at `pos`; an empty text clears it. */
+      setReferenceLocator: (pos: number, locator: string) => ReturnType;
+    };
+  }
+}
+export interface ReferenceOptions {
+  HTMLAttributes: Record<string, unknown>;
+  /** `[@` popup (client only, see reference-suggestion.ts); `null` = schema only (server, Markdown). */
+  suggestion: Omit<SuggestionOptions<ReferenceAttrs, ReferenceAttrs>, 'editor'> | null;
+}
+/** Own key, so the `[@` popup runs next to the `@` mention and `#` tag popups. */
+export declare const ReferenceSuggestionPluginKey: PluginKey<any>;
+/**
+ * Inline chip pointing at a Baustein of the document (a paper, a recording, a note): shared by the client editor and
+ * the server (collab schema, Markdown). Markdown form `[@<block id>, <locator>]`; text of that form becomes chips again
+ * through `referencesFromText` (the composites feature's `normalize` stage). The client adds the node view and the popup.
+ */
+export declare const ReferenceNode: Node<ReferenceOptions, any>;
+//#endregion
+//# sourceMappingURL=reference.d.ts.map

package/dist/features/composites/reference.js

@@ -0,0 +1,148 @@
+import { Extension, Node, mergeAttributes } from "@tiptap/core";
+import { PluginKey } from "@tiptap/pm/state";
+import { Suggestion } from "@tiptap/suggestion";
+//#region src/features/composites/reference.ts
+const REFERENCE_NODE = "reference";
+/** `[@<target>]` / `[@<target>, <locator>]`, the chip's Markdown form; `]` in a locator is escaped as `\]`. */
+function referenceMarkdown(attrs) {
+	const locator = attrs.locator?.trim();
+	return locator ? `[@${attrs.target}, ${locator.replace(/\]/g, "\\]")}]` : `[@${attrs.target}]`;
+}
+/** Pattern of the chip's Markdown form (capture 1: block id, capture 2: locator with `\]` still escaped); compile with `new RegExp(..., 'g')`. */
+const REFERENCE_TOKEN_SOURCE = String.raw`\[@([0-9a-f-]{36})(?:,\s*((?:\\\]|[^\]])+))?\]`;
+/** Own key, so the `[@` popup runs next to the `@` mention and `#` tag popups. */
+const ReferenceSuggestionPluginKey = new PluginKey("referenceSuggestion");
+/**
+* Inline chip pointing at a Baustein of the document (a paper, a recording, a note): shared by the client editor and
+* the server (collab schema, Markdown). Markdown form `[@<block id>, <locator>]`; text of that form becomes chips again
+* through `referencesFromText` (the composites feature's `normalize` stage). The client adds the node view and the popup.
+*/
+const ReferenceNode = Node.create({
+	name: REFERENCE_NODE,
+	group: "inline",
+	inline: true,
+	atom: true,
+	selectable: true,
+	priority: 99,
+	markdownTokenizer: {
+		name: "referenceToken",
+		level: "inline",
+		start: (src) => src.search(/\[@[0-9a-f-]{36}/),
+		tokenize: (src) => {
+			const match = new RegExp(`^${REFERENCE_TOKEN_SOURCE}`).exec(src);
+			return match ? {
+				type: "text",
+				raw: match[0],
+				text: match[0]
+			} : void 0;
+		}
+	},
+	addOptions() {
+		return {
+			HTMLAttributes: { class: "reference" },
+			suggestion: null
+		};
+	},
+	addAttributes() {
+		return {
+			target: {
+				default: "",
+				parseHTML: (el) => el.getAttribute("data-target") ?? "",
+				renderHTML: (attrs) => ({ "data-target": attrs.target })
+			},
+			documentId: {
+				default: null,
+				parseHTML: (el) => el.getAttribute("data-document"),
+				renderHTML: (attrs) => attrs.documentId ? { "data-document": attrs.documentId } : {}
+			},
+			locator: {
+				default: null,
+				parseHTML: (el) => el.getAttribute("data-locator"),
+				renderHTML: (attrs) => attrs.locator ? { "data-locator": attrs.locator } : {}
+			},
+			label: {
+				default: "",
+				parseHTML: (el) => el.getAttribute("data-label") ?? el.textContent ?? "",
+				renderHTML: (attrs) => ({ "data-label": attrs.label })
+			}
+		};
+	},
+	parseHTML() {
+		return [{ tag: `span[data-type="${this.name}"]` }];
+	},
+	renderHTML({ node, HTMLAttributes }) {
+		return [
+			"span",
+			mergeAttributes({ "data-type": this.name }, this.options.HTMLAttributes, HTMLAttributes),
+			String(node.attrs.label ?? "")
+		];
+	},
+	renderText: ({ node }) => referenceMarkdown(node.attrs),
+	renderMarkdown: (node) => referenceMarkdown({
+		target: String(node.attrs?.target ?? ""),
+		locator: typeof node.attrs?.locator === "string" ? node.attrs.locator : null
+	}),
+	addCommands() {
+		return {
+			insertReference: (attrs) => ({ commands }) => commands.insertContent([{
+				type: this.name,
+				attrs
+			}, {
+				type: "text",
+				text: " "
+			}]),
+			setReferenceLocator: (pos, locator) => ({ tr, dispatch }) => {
+				const node = tr.doc.nodeAt(pos);
+				if (node?.type.name !== this.name) return false;
+				if (dispatch) tr.setNodeMarkup(pos, void 0, {
+					...node.attrs,
+					locator: locator.trim() || null
+				});
+				return true;
+			}
+		};
+	},
+	addExtensions() {
+		const { suggestion } = this.options;
+		return suggestion ? [ReferenceSuggestion.configure({ suggestion })] : [];
+	}
+});
+/**
+* The `[@` popup of ReferenceNode. Priority 101 (like TagNode), above core's Keymap (100): extension priority orders
+* the ProseMirror plugins' `handleKeyDown`, and with a lower one Enter would split the paragraph instead of picking.
+*/
+const ReferenceSuggestion = Extension.create({
+	name: "referenceSuggestion",
+	priority: 101,
+	addOptions() {
+		return { suggestion: null };
+	},
+	addProseMirrorPlugins() {
+		const { suggestion } = this.options;
+		if (!suggestion) return [];
+		const { allow, ...rest } = suggestion;
+		return [Suggestion({
+			pluginKey: ReferenceSuggestionPluginKey,
+			char: "[@",
+			allowSpaces: true,
+			allow: (p) => allow?.(p) ?? true,
+			command: ({ editor, range, props }) => {
+				if (editor.view.state.selection.$to.nodeAfter?.text?.startsWith(" ")) range.to += 1;
+				editor.chain().focus().insertContentAt(range, [{
+					type: REFERENCE_NODE,
+					attrs: props
+				}, {
+					type: "text",
+					text: " "
+				}]).run();
+				editor.view.dom.ownerDocument.defaultView?.getSelection()?.collapseToEnd();
+			},
+			...rest,
+			editor: this.editor
+		})];
+	}
+});
+//#endregion
+export { REFERENCE_NODE, REFERENCE_TOKEN_SOURCE, ReferenceNode, ReferenceSuggestion, ReferenceSuggestionPluginKey, referenceMarkdown };
+
+//# sourceMappingURL=reference.js.map

package/dist/features/composites/reference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference.js","names":[],"sources":["../../../src/features/composites/reference.ts"],"sourcesContent":["import { Extension, mergeAttributes, Node } from '@tiptap/core'\nimport { PluginKey } from '@tiptap/pm/state'\nimport { Suggestion, type SuggestionOptions } from '@tiptap/suggestion'\n\n/**\n * Attributes of a reference chip. `target` is the block ID of the referenced Baustein; `label` caches its display text\n * for the cases the target cannot be resolved (the node view shows the live label and only falls back to this one).\n */\nexport interface ReferenceAttrs {\n  target: string\n  /** Document of the target; `null` = this document (cross-document references are not resolved yet). */\n  documentId: string | null\n  /** Position inside the target's source: `S. 12` (PDF page), `03:14` (recording time); `null` = the whole Baustein. */\n  locator: string | null\n  label: string\n}\n\nexport const REFERENCE_NODE = 'reference'\n\n/** Trigger of the popup. Two characters: `[@` is the Markdown form, so typing it by hand and picking from the list agree. */\nexport const REFERENCE_TRIGGER = '[@'\n\n/** `[@<target>]` / `[@<target>, <locator>]`, the chip's Markdown form; `]` in a locator is escaped as `\\]`. */\nexport function referenceMarkdown(attrs: Pick<ReferenceAttrs, 'target' | 'locator'>): string {\n  const locator = attrs.locator?.trim()\n  return locator ? `[@${attrs.target}, ${locator.replace(/\\]/g, '\\\\]')}]` : `[@${attrs.target}]`\n}\n\n/** Pattern of the chip's Markdown form (capture 1: block id, capture 2: locator with `\\]` still escaped); compile with `new RegExp(..., 'g')`. */\nexport const REFERENCE_TOKEN_SOURCE = String.raw`\\[@([0-9a-f-]{36})(?:,\\s*((?:\\\\\\]|[^\\]])+))?\\]`\n\ndeclare module '@tiptap/core' {\n  interface Commands<ReturnType> {\n    reference: {\n      /** Inserts a reference chip (followed by a space) at the selection. */\n      insertReference: (attrs: Partial<ReferenceAttrs> & Pick<ReferenceAttrs, 'target'>) => ReturnType\n      /** Sets the locator of the reference chip at `pos`; an empty text clears it. */\n      setReferenceLocator: (pos: number, locator: string) => ReturnType\n    }\n  }\n}\n\nexport interface ReferenceOptions {\n  HTMLAttributes: Record<string, unknown>\n  /** `[@` popup (client only, see reference-suggestion.ts); `null` = schema only (server, Markdown). */\n  suggestion: Omit<SuggestionOptions<ReferenceAttrs, ReferenceAttrs>, 'editor'> | null\n}\n\n/** Own key, so the `[@` popup runs next to the `@` mention and `#` tag popups. */\nexport const ReferenceSuggestionPluginKey = new PluginKey('referenceSuggestion')\n\n/**\n * Inline chip pointing at a Baustein of the document (a paper, a recording, a note): shared by the client editor and\n * the server (collab schema, Markdown). Markdown form `[@<block id>, <locator>]`; text of that form becomes chips again\n * through `referencesFromText` (the composites feature's `normalize` stage). The client adds the node view and the popup.\n */\nexport const ReferenceNode = Node.create<ReferenceOptions>({\n  name: REFERENCE_NODE,\n  group: 'inline',\n  inline: true,\n  atom: true,\n  selectable: true,\n  // Just below Mention (100): TipTap's Markdown manager registers the tokenizers in priority order and marked tries the\n  // last registered first, so `markdownTokenizer` below sees `[@<id>]` before Mention's `[@ ...]` shortcode does.\n  priority: 99,\n\n  // Claims `[@<block id>, <locator>]` as plain text, so Mention's tokenizer (which takes every `[@...]`) leaves it alone;\n  // the composites feature's `normalize` stage turns it into a chip when the id belongs to a Baustein of the document.\n  markdownTokenizer: {\n    name: 'referenceToken',\n    level: 'inline',\n    start: src => src.search(/\\[@[0-9a-f-]{36}/),\n    tokenize: (src) => {\n      const match = new RegExp(`^${REFERENCE_TOKEN_SOURCE}`).exec(src)\n      return match ? { type: 'text', raw: match[0], text: match[0] } : undefined\n    },\n  },\n\n  addOptions() {\n    return { HTMLAttributes: { class: 'reference' }, suggestion: null }\n  },\n\n  addAttributes() {\n    return {\n      target: {\n        default: '',\n        parseHTML: el => el.getAttribute('data-target') ?? '',\n        renderHTML: attrs => ({ 'data-target': attrs.target }),\n      },\n      documentId: {\n        default: null,\n        parseHTML: el => el.getAttribute('data-document'),\n        renderHTML: attrs => attrs.documentId ? { 'data-document': attrs.documentId } : {},\n      },\n      locator: {\n        default: null,\n        parseHTML: el => el.getAttribute('data-locator'),\n        renderHTML: attrs => attrs.locator ? { 'data-locator': attrs.locator } : {},\n      },\n      label: {\n        default: '',\n        parseHTML: el => el.getAttribute('data-label') ?? el.textContent ?? '',\n        renderHTML: attrs => ({ 'data-label': attrs.label }),\n      },\n    }\n  },\n\n  parseHTML() {\n    return [{ tag: `span[data-type=\"${this.name}\"]` }]\n  },\n\n  renderHTML({ node, HTMLAttributes }) {\n    return ['span', mergeAttributes({ 'data-type': this.name }, this.options.HTMLAttributes, HTMLAttributes), String(node.attrs.label ?? '')]\n  },\n\n  renderText: ({ node }) => referenceMarkdown(node.attrs as ReferenceAttrs),\n\n  // Markdown export (editor.getMarkdown(), AI context/selection) writes the chip as `[@<id>, <locator>]`.\n  renderMarkdown: node => referenceMarkdown({ target: String(node.attrs?.target ?? ''), locator: typeof node.attrs?.locator === 'string' ? node.attrs.locator : null }),\n\n  addCommands() {\n    return {\n      insertReference: attrs => ({ commands }) =>\n        commands.insertContent([{ type: this.name, attrs }, { type: 'text', text: ' ' }]),\n      setReferenceLocator: (pos, locator) => ({ tr, dispatch }) => {\n        const node = tr.doc.nodeAt(pos)\n        if (node?.type.name !== this.name) return false\n        if (dispatch) tr.setNodeMarkup(pos, undefined, { ...node.attrs, locator: locator.trim() || null })\n        return true\n      },\n    }\n  },\n\n  // The popup lives in a companion extension (see `ReferenceSuggestion`): it must rank above TipTap's core keymap\n  // (100) to see Enter first, which this node cannot (its priority orders the Markdown tokenizer).\n  addExtensions() {\n    const { suggestion } = this.options\n    return suggestion ? [ReferenceSuggestion.configure({ suggestion })] : []\n  },\n})\n\n/**\n * The `[@` popup of ReferenceNode. Priority 101 (like TagNode), above core's Keymap (100): extension priority orders\n * the ProseMirror plugins' `handleKeyDown`, and with a lower one Enter would split the paragraph instead of picking.\n */\nexport const ReferenceSuggestion = Extension.create<{ suggestion: NonNullable<ReferenceOptions['suggestion']> | null }>({\n  name: 'referenceSuggestion',\n  priority: 101,\n\n  addOptions() {\n    return { suggestion: null }\n  },\n\n  addProseMirrorPlugins() {\n    const { suggestion } = this.options\n    if (!suggestion) return []\n    const { allow, ...rest } = suggestion\n    return [Suggestion<ReferenceAttrs, ReferenceAttrs>({\n      pluginKey: ReferenceSuggestionPluginKey,\n      char: REFERENCE_TRIGGER,\n      allowSpaces: true,\n      allow: p => allow?.(p) ?? true,\n      command: ({ editor, range, props }) => {\n        // Reuse a following space instead of doubling it (as Mention does).\n        const nodeAfter = editor.view.state.selection.$to.nodeAfter\n        if (nodeAfter?.text?.startsWith(' ')) range.to += 1\n        editor.chain().focus()\n          .insertContentAt(range, [{ type: REFERENCE_NODE, attrs: props }, { type: 'text', text: ' ' }])\n          .run()\n        editor.view.dom.ownerDocument.defaultView?.getSelection()?.collapseToEnd()\n      },\n      ...rest,\n      editor: this.editor,\n    })]\n  },\n})\n"],"mappings":"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"}

package/dist/features/composites/reveal-source.d.ts

@@ -0,0 +1,32 @@
+import { Editor, Extension } from "@tiptap/core";
+//#region src/features/composites/reveal-source.d.ts
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    sourceReveal: {
+      /** Seek and play the media of the source-holding Baustein enclosing `pos` to `seconds`; silent when there is none. */
+      seekSource: (pos: number, seconds: number) => ReturnType;
+    };
+  }
+}
+/** Where in the source a locator points: a time in seconds (`3:07`) or a PDF page (`S. 12`, `p. 12`, `12`). */
+export type SourceLocator = {
+  seconds: number;
+} | {
+  page: number;
+};
+/** Parses a reference locator; null for anything that is not a time or a page number. */
+export declare function parseLocator(locator: string | null | undefined): SourceLocator | null;
+/**
+ * Seeks and plays the audio/video of the nearest source-holding Baustein around `pos` (a transcript segment inside a
+ * rendition reaches the recording that way). Silent when there is no source or no media element.
+ */
+export declare function seekSource(editor: Editor, pos: number, seconds: number): void;
+/**
+ * Shows the source of Baustein `targetId` at `locator`: a `mm:ss` time seeks the media, a page number opens a PDF source
+ * at that page; then the source block flashes. Silent when the target or its source is gone.
+ */
+export declare function revealSource(editor: Editor, targetId: string, locator: string | null): void;
+/** Registers `seekSource` as an editor command, so features that must not import composites (transcript) can call it. */
+export declare const SourceReveal: Extension<any, any>;
+//#endregion
+//# sourceMappingURL=reveal-source.d.ts.map

package/dist/features/composites/reveal-source.js

@@ -0,0 +1,89 @@
+import { blockIdOf, findBlockById } from "../../core/schema/block-ids.js";
+import { sourceOf } from "./derivation.js";
+import { compositeKindsOf } from "./nodes.js";
+import { Extension } from "@tiptap/core";
+//#region src/features/composites/reveal-source.ts
+/** DOM event the PDF file view listens for; `detail` is the 1-based page to open the viewer at. */
+const REVEAL_PAGE_EVENT = "sk-reveal-page";
+const TIME_LOCATOR = /^(\d+):(\d{2})$/;
+const PAGE_LOCATOR = /^(?:S\.|p\.)?\s*(\d+)$/i;
+/** Parses a reference locator; null for anything that is not a time or a page number. */
+function parseLocator(locator) {
+	const text = locator?.trim();
+	if (!text) return null;
+	const time = TIME_LOCATOR.exec(text);
+	if (time) return { seconds: Number(time[1]) * 60 + Number(time[2]) };
+	const page = PAGE_LOCATOR.exec(text);
+	if (page && Number(page[1]) > 0) return { page: Number(page[1]) };
+	return null;
+}
+/** The source block of the composite `composite` at `pos` with its document position, or null. */
+function sourceAt(editor, composite, pos) {
+	const source = sourceOf(composite, compositeKindsOf(editor));
+	if (!source) return null;
+	let sourcePos = pos + 1;
+	for (let i = 0; i < source.index; i++) sourcePos += composite.child(i).nodeSize;
+	return {
+		node: source.node,
+		pos: sourcePos
+	};
+}
+/** The element of the node view at `pos` that carries the view's own listeners (the framework's wrapper), or null. */
+function viewElement(editor, pos) {
+	const dom = editor.view.nodeDOM(pos);
+	if (!(dom instanceof HTMLElement)) return null;
+	return dom.matches("[data-node-view-wrapper]") ? dom : dom.querySelector("[data-node-view-wrapper]") ?? dom;
+}
+function playAt(editor, sourcePos, seconds) {
+	const dom = editor.view.nodeDOM(sourcePos);
+	if (!(dom instanceof HTMLElement)) return false;
+	const media = dom.matches("audio,video") ? dom : dom.querySelector("audio,video");
+	if (!media) return false;
+	media.currentTime = seconds;
+	media.play().catch(() => {});
+	return true;
+}
+/**
+* Seeks and plays the audio/video of the nearest source-holding Baustein around `pos` (a transcript segment inside a
+* rendition reaches the recording that way). Silent when there is no source or no media element.
+*/
+function seekSource(editor, pos, seconds) {
+	if (!Number.isFinite(seconds) || seconds < 0) return;
+	const $pos = editor.state.doc.resolve(pos);
+	for (let depth = $pos.depth; depth >= 0; depth--) {
+		const composite = $pos.node(depth);
+		if (composite.type.name !== "composite") continue;
+		const source = sourceAt(editor, composite, $pos.before(depth));
+		if (!source) continue;
+		playAt(editor, source.pos, seconds);
+		return;
+	}
+}
+/**
+* Shows the source of Baustein `targetId` at `locator`: a `mm:ss` time seeks the media, a page number opens a PDF source
+* at that page; then the source block flashes. Silent when the target or its source is gone.
+*/
+function revealSource(editor, targetId, locator) {
+	const target = findBlockById(editor.state.doc, targetId);
+	if (!target) return;
+	const source = sourceAt(editor, target.node, target.pos);
+	if (!source) return;
+	const parsed = parseLocator(locator);
+	if (parsed && "seconds" in parsed) playAt(editor, source.pos, parsed.seconds);
+	else if (parsed && source.node.type.name === "file" && source.node.attrs.mimeType === "application/pdf") viewElement(editor, source.pos)?.dispatchEvent(new CustomEvent(REVEAL_PAGE_EVENT, { detail: parsed.page }));
+	editor.commands.revealBlock(blockIdOf(source.node) ?? targetId);
+}
+/** Registers `seekSource` as an editor command, so features that must not import composites (transcript) can call it. */
+const SourceReveal = Extension.create({
+	name: "sourceReveal",
+	addCommands() {
+		return { seekSource: (pos, seconds) => ({ editor }) => {
+			seekSource(editor, pos, seconds);
+			return true;
+		} };
+	}
+});
+//#endregion
+export { REVEAL_PAGE_EVENT, SourceReveal, parseLocator, revealSource, seekSource };
+
+//# sourceMappingURL=reveal-source.js.map