@aicayzer/inkkit 0.4.1 → 0.5.0

package/dist/chunks/{core-CisgnAp-.js → core-fEBASTpF.js}

@@ -28436,6 +28436,24 @@ var formatLossCodes = [
 	"mark-spaces",
 	"empty-line"
 ];
+/** The closed list of failure codes. The API reference describes each one. */
+var editorErrorCodes = [
+	"not-ready",
+	"destroyed",
+	"stale-document",
+	"composition",
+	"operation-pending",
+	"read-only",
+	"invalid-argument",
+	"invalid-range",
+	"preservation",
+	"image-unavailable",
+	"diagram-unavailable",
+	"file-unavailable",
+	"clipboard-unavailable",
+	"slash-command-failed",
+	"internal"
+];
 /** Every failure InkKit reports. Hosts branch on `code`; `message` is for logs. When the failure
 *  started elsewhere, such as in an adapter, the host clipboard or the renderer, `cause` holds the
 *  original error. */
@@ -28793,6 +28811,208 @@ function mermaidPreview(store, onError) {
 	});
 }
 //#endregion
+//#region src/preserve-error.ts
+var PreservationError = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "PreservationError";
+	}
+};
+var PreservationRefusal = class extends PreservationError {
+	reason;
+	constructor(reason, message) {
+		super(message);
+		this.reason = reason;
+	}
+};
+var MarkdownParseRefusal = class extends InkKitError {
+	constructor() {
+		super("preservation", "The Markdown cannot be shown without losing part of it");
+	}
+};
+function isPreservationRefusal(error) {
+	return error instanceof PreservationRefusal || error instanceof MarkdownParseRefusal;
+}
+//#endregion
+//#region src/diagnostics.ts
+var observers = /* @__PURE__ */ new WeakMap();
+function observePreservation(ctx, observer) {
+	if (observer) observers.set(ctx, observer);
+	else observers.delete(ctx);
+}
+function tracePreservation(ctx, detail) {
+	observers.get(ctx)?.(detail);
+}
+var Diagnostics = class {
+	state;
+	enabled = false;
+	sessionId = randomSession();
+	started = performance.now();
+	sequence = 0;
+	events = [];
+	incident;
+	dispose;
+	latestState = {
+		ready: false,
+		revision: 0,
+		format: "md",
+		mode: "formatted",
+		editable: false,
+		composing: false,
+		pending: false
+	};
+	currentState() {
+		try {
+			return this.latestState = this.state();
+		} catch {
+			return this.latestState;
+		}
+	}
+	capture(detail) {
+		try {
+			this.record(detail);
+		} catch {}
+	}
+	constructor(state) {
+		this.state = state;
+	}
+	setEnabled(enabled, root, ctx) {
+		if (enabled === this.enabled) return;
+		this.dispose?.();
+		this.dispose = void 0;
+		observePreservation(ctx);
+		this.enabled = enabled;
+		this.events = [];
+		this.incident = void 0;
+		this.sequence = 0;
+		if (!enabled) return;
+		this.sessionId = randomSession();
+		this.started = performance.now();
+		const listeners = [];
+		const listen = (target, name, run) => {
+			target.addEventListener(name, run, true);
+			listeners.push(() => target.removeEventListener(name, run, true));
+		};
+		for (const name of ["beforeinput", "input"]) listen(root, name, (event) => {
+			const inputType = event.inputType ?? "";
+			const input = inputType.includes("Composition") ? "composition" : inputType.startsWith("delete") ? "delete" : inputType.includes("Paste") ? "paste" : inputType.includes("Drop") ? "drop" : inputType.startsWith("history") ? "history" : inputType.startsWith("format") ? "format" : inputType === "insertText" ? "text" : "other";
+			this.capture({
+				kind: "input",
+				phase: name === "beforeinput" ? "before" : "after",
+				input
+			});
+		});
+		for (const name of ["compositionstart", "compositionend"]) listen(root, name, () => this.capture({
+			kind: "composition",
+			phase: name === "compositionstart" ? "start" : "end"
+		}));
+		for (const name of ["focusin", "focusout"]) listen(root, name, () => this.capture({
+			kind: "focus",
+			phase: name === "focusin" ? "in" : "out"
+		}));
+		listen(root.ownerDocument, "selectionchange", () => {
+			const document = root.ownerDocument;
+			if (root.contains(document.activeElement) || root.contains(document.getSelection()?.anchorNode ?? null)) this.capture({ kind: "selection" });
+		});
+		this.dispose = () => listeners.forEach((remove) => remove());
+		observePreservation(ctx, (detail) => this.capture(detail));
+		this.capture({ kind: "enabled" });
+	}
+	record(detail) {
+		if (!this.enabled) return;
+		const safe = { ...detail };
+		if (safe.code && !editorErrorCodes.includes(safe.code)) safe.code = "internal";
+		if (safe.reason && ![
+			"matching-budget",
+			"source-location",
+			"reopen-mismatch",
+			"parse-refusal",
+			"unexpected"
+		].includes(safe.reason)) safe.reason = "unexpected";
+		const event = {
+			...safe,
+			sequence: ++this.sequence,
+			elapsedMs: Math.round(performance.now() - this.started),
+			state: this.currentState()
+		};
+		this.events.push(event);
+		if (this.events.length > 200) this.events.shift();
+		if (this.incident) {
+			if (this.incident.tail.length < 40) this.incident.tail.push(event);
+		} else if (safe.code === "preservation" || safe.code === "internal" || safe.kind === "preservation" && safe.phase === "refused") this.incident = {
+			triggerSequence: event.sequence,
+			events: this.events.slice(),
+			tail: []
+		};
+	}
+	report(presentation) {
+		return structuredClone({
+			schemaVersion: 1,
+			enabled: this.enabled,
+			sessionId: this.sessionId,
+			state: this.currentState(),
+			events: this.events,
+			...this.incident ? { incident: this.incident } : {},
+			...presentation ? { presentation } : {}
+		});
+	}
+	destroy(ctx) {
+		this.dispose?.();
+		observePreservation(ctx);
+		this.dispose = void 0;
+		this.enabled = false;
+		this.events = [];
+		this.incident = void 0;
+	}
+};
+function diagnosticOperation(name) {
+	if (name === "snapshot") return "snapshot";
+	if (name === "undo" || name === "redo") return "history";
+	if (name === "loadDocument" || name === "reloadDocument") return "load";
+	if (name.startsWith("set")) return "configuration";
+	if (name.includes("Snapshot") || name === "convertDocument") return "output";
+	if (name.includes("TextRange") || name === "focus" || name === "blur") return "selection";
+	if (name === "destroy") return "lifecycle";
+	if ([
+		"insertText",
+		"replaceSource",
+		"paste",
+		"pasteAsPlainText",
+		"format",
+		"table",
+		"moveBlock",
+		"replace",
+		"replaceAll",
+		"insertImages",
+		"appendImages",
+		"insertFootnote",
+		"insertPaths",
+		"editReferenceDefinition"
+	].includes(name)) return "edit";
+	return "other";
+}
+var diagnosticNumber = (value) => Number.isFinite(value) ? Math.round(Math.max(-1e7, Math.min(1e7, value)) * 100) / 100 : 0;
+function diagnosticReason(error) {
+	try {
+		for (let depth = 0; depth < 8 && error instanceof Error; depth++) {
+			if (error instanceof MarkdownParseRefusal) return "parse-refusal";
+			if (error instanceof PreservationRefusal) {
+				const reason = error.reason;
+				return reason === "matching-budget" || reason === "source-location" || reason === "reopen-mismatch" ? reason : "unexpected";
+			}
+			error = Object.getOwnPropertyDescriptor(error, "cause")?.value;
+		}
+	} catch {}
+	return "unexpected";
+}
+function randomSession() {
+	const bytes = crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(16));
+	bytes[6] = bytes[6] & 15 | 64;
+	bytes[8] = bytes[8] & 63 | 128;
+	const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+//#endregion
 //#region src/bom.ts
 function leadingBOMLength(text) {
 	return text.startsWith("") ? 1 : 0;
@@ -44160,29 +44380,6 @@ function languageFence(value, language) {
 	};
 }
 //#endregion
-//#region src/preserve-error.ts
-var PreservationError = class extends Error {
-	constructor(message, options) {
-		super(message, options);
-		this.name = "PreservationError";
-	}
-};
-var PreservationRefusal = class extends PreservationError {
-	reason;
-	constructor(reason, message) {
-		super(message);
-		this.reason = reason;
-	}
-};
-var MarkdownParseRefusal = class extends InkKitError {
-	constructor() {
-		super("preservation", "The Markdown cannot be shown without losing part of it");
-	}
-};
-function isPreservationRefusal(error) {
-	return error instanceof PreservationRefusal || error instanceof MarkdownParseRefusal;
-}
-//#endregion
 //#region src/parser.ts
 /**
 * Milkdown's parser state, except that it throws where Milkdown would drop content. Milkdown
@@ -44309,6 +44506,10 @@ async function resolveFile(adapter, reference, context) {
 		"error"
 	].includes(presentation.kind)) throw new TypeError("File adapter returned an unsupported presentation");
 	if (presentation.label !== void 0 && typeof presentation.label !== "string") throw new TypeError("File presentation label must be text");
+	if (presentation.kind === "file") {
+		if (presentation.layout !== void 0 && presentation.layout !== "fill") throw new TypeError("File presentation layout must be fill");
+		if (presentation.activation !== void 0 && presentation.activation !== "card") throw new TypeError("File presentation activation must be card");
+	}
 	if (presentation.kind === "error" && typeof presentation.message !== "string") throw new TypeError("File presentation error must include a message");
 	if ("url" in presentation) {
 		if (typeof presentation.url !== "string" || !presentation.url.trim()) throw new TypeError("File presentation needs a resource URL");
@@ -51050,6 +51251,12 @@ var Preservation = class Preservation {
 		try {
 			return this.serializeWith(doc);
 		} catch (cause) {
+			tracePreservation(this.ctx, {
+				kind: "preservation",
+				phase: "refused",
+				code: "preservation",
+				reason: cause instanceof PreservationRefusal ? cause.reason : "unexpected"
+			});
 			if (cause instanceof PreservationError || isPreservationRefusal(cause)) throw cause;
 			throw new PreservationError("Cannot preserve the edited Markdown", { cause });
 		} finally {
@@ -51057,14 +51264,26 @@ var Preservation = class Preservation {
 		}
 	}
 	serializeWith(doc) {
-		if (this.unchanged(doc)) return this.source;
+		if (this.unchanged(doc)) {
+			tracePreservation(this.ctx, {
+				kind: "preservation",
+				path: "unchanged"
+			});
+			return this.source;
+		}
 		let local = this.localEdits(doc);
+		let path = "local";
 		if (local === void 0) try {
+			path = "regions";
 			local = this.regions(doc);
 		} catch (error) {
 			if (!isPreservationRefusal(error)) throw error;
 			local = void 0;
 		}
+		tracePreservation(this.ctx, {
+			kind: "preservation",
+			path: local === void 0 ? "whole" : path
+		});
 		return local === void 0 ? this.wholeDocument(doc) : this.checked(doc, local);
 	}
 	unchanged(doc) {
@@ -56472,6 +56691,8 @@ var ImageView = class {
 	resolution;
 	previewFailed = false;
 	suspended = false;
+	/** True while the card is itself the Open control (`activation: 'card'`). */
+	cardKeys = false;
 	/** Present when the host sets `files`, which then shows every image. */
 	runtime;
 	constructor(node, view, getPos, adapter, host, files, cache, canMutate = () => true) {
@@ -56527,7 +56748,7 @@ var ImageView = class {
 		return true;
 	}
 	stopEvent(event) {
-		return event.target instanceof Element && !!event.target.closest(".inkkit-image-handle, .inkkit-file-control, audio, video, iframe");
+		return event.target instanceof Element && (!!event.target.closest(".inkkit-image-handle, .inkkit-file-control, audio, video, iframe") || event.type === "keydown" && event.target === this.element && this.cardKeys);
 	}
 	ignoreMutation() {
 		return true;
@@ -56644,7 +56865,25 @@ var ImageView = class {
 		const selection = NodeSelection.create(state.doc, pos);
 		if (!state.selection.eq(selection)) this.view.dispatch(state.tr.setSelection(selection));
 	}
-	card(label, status, retry = false) {
+	cardKey = (event) => {
+		if (event.target !== this.element || event.isComposing) return;
+		if (event.key !== "Enter" && event.key !== " ") return;
+		event.preventDefault();
+		this.activate();
+	};
+	cardClick = () => this.activate();
+	/** Makes the whole card the one control that opens the file, in place of the arrow button. */
+	activateCard(label) {
+		const { element } = this;
+		element.setAttribute("role", "button");
+		element.setAttribute("aria-label", `${this.runtime.labels.fileOpen} ${label}`);
+		element.tabIndex = 0;
+		element.dataset.inkkitFileActivation = "card";
+		this.cardKeys = true;
+		element.addEventListener("click", this.cardClick);
+		element.addEventListener("keydown", this.cardKey);
+	}
+	card(label, status, retry = false, activation = false) {
 		if (this.resolution?.state.status !== "loading" && !this.handle) this.restoreResizeFocus = false;
 		const footer = document.createElement("span");
 		footer.className = "inkkit-file-footer";
@@ -56655,7 +56894,8 @@ var ImageView = class {
 		text.textContent = label;
 		text.title = label;
 		name.append(text);
-		if (this.runtime?.adapter.open) {
+		if (activation && this.runtime?.adapter.open) this.activateCard(label);
+		else if (this.runtime?.adapter.open) {
 			const open = this.button("", this.activate);
 			open.classList.add("inkkit-file-open");
 			open.setAttribute("aria-label", `${this.runtime.labels.fileOpen} ${label}`);
@@ -56691,6 +56931,12 @@ var ImageView = class {
 		} : splitAlt(String(this.node.attrs.alt ?? ""));
 		this.width = width;
 		this.element.textContent = "";
+		this.element.removeEventListener("click", this.cardClick);
+		this.element.removeEventListener("keydown", this.cardKey);
+		this.element.removeAttribute("tabindex");
+		this.element.removeAttribute("data-inkkit-file-activation");
+		this.element.removeAttribute("data-inkkit-file-layout");
+		this.cardKeys = false;
 		this.image = void 0;
 		this.handle = void 0;
 		if (this.runtime) {
@@ -56754,6 +57000,9 @@ var ImageView = class {
 				this.pdf = pdf;
 				this.element.append(pdf);
 				this.card(label, this.runtime.labels.filePDFPreview);
+			} else if (presentation.kind === "file") {
+				if (presentation.layout === "fill") this.element.dataset.inkkitFileLayout = "fill";
+				this.card(label, void 0, false, presentation.activation === "card");
 			} else this.card(label);
 			this.restoreHandleFocus();
 			return;
@@ -56970,7 +57219,7 @@ async function createMilkdownEditor(root, options, runtime) {
 				return true;
 			}
 		}));
-	}).use(labelsCtx).use(linkSchemesCtx).use(formatInputCtx).use(richTextGuard).use(runtime.plugins.paste).use(visibleClipboard).use(runtime.plugins.suggestions).use(runtime.plugins.keymap).use(createDialect(Boolean(options.images || options.files), Boolean(options.wikiLinks), Boolean(options.files))).use(codeControlCtx).use(codeControlsPlugin(() => runtime.visibleRect())).use(tablePlugins).use(tableBlock).use(runtime.plugins.change).use(runtime.plugins.historyInput).use(history).use(clipboard).use(cursor).use(taskListPlugin((operation) => runtime.mutate(operation))).use(undoTypedRule).use(quoteBackspace).use(calloutEnter).use(literalEnter).use(literalReread).use(listItemBackspace).use(nestedItemEnter).use(rejoinLists).use(movedListItems).use(textInputPolicy).use(runtime.copy ? codeCopyPlugin((text) => runtime.copy?.(text)) : []).use(placeholderPlugin).use(options.rendering?.codeHighlighting === false ? [] : (await import("./highlight-CqtvWKCp.js")).highlightPlugin).use(options.rendering?.diagramPreview === false || !diagramsAvailable() ? [] : mermaidPreview(runtime.diagrams, (error) => runtime.report(error))).use(selectionPlugin).use($prose(() => search())).use(runtime.plugins.policy).use(options.wikiLinks ? wikiLinkView(options.wikiLinks, {
+	}).use(labelsCtx).use(linkSchemesCtx).use(formatInputCtx).use(richTextGuard).use(runtime.plugins.paste).use(visibleClipboard).use(runtime.plugins.suggestions).use(runtime.plugins.keymap).use(createDialect(Boolean(options.images || options.files), Boolean(options.wikiLinks), Boolean(options.files))).use(codeControlCtx).use(codeControlsPlugin(() => runtime.visibleRect())).use(tablePlugins).use(tableBlock).use(runtime.plugins.change).use(runtime.plugins.historyInput).use(history).use(clipboard).use(cursor).use(taskListPlugin((operation) => runtime.mutate(operation))).use(undoTypedRule).use(quoteBackspace).use(calloutEnter).use(literalEnter).use(literalReread).use(listItemBackspace).use(nestedItemEnter).use(rejoinLists).use(movedListItems).use(textInputPolicy).use(runtime.copy ? codeCopyPlugin((text) => runtime.copy?.(text)) : []).use(placeholderPlugin).use(options.rendering?.codeHighlighting === false ? [] : (await import("./highlight-D3LQRB1-.js")).highlightPlugin).use(options.rendering?.diagramPreview === false || !diagramsAvailable() ? [] : mermaidPreview(runtime.diagrams, (error) => runtime.report(error))).use(selectionPlugin).use($prose(() => search())).use(runtime.plugins.policy).use(options.wikiLinks ? wikiLinkView(options.wikiLinks, {
 		capture: () => runtime.capture(),
 		active: () => runtime.active(),
 		labels: {
@@ -59576,6 +59825,7 @@ var stateEvents = ["changed", "commandStateChanged"];
 var InkKitEditor = class InkKitEditor {
 	options;
 	editor;
+	diagnostics = new Diagnostics(() => this.diagnosticState());
 	document = new EditorDocument({
 		ctx: () => this.editor.ctx,
 		literal: () => this.literalSurface,
@@ -59710,7 +59960,7 @@ var InkKitEditor = class InkKitEditor {
 		try {
 			markdown = this.document.currentText(view.state.doc);
 		} catch (error) {
-			this.events.error?.(coded(error, "preservation"));
+			this.report(coded(error, "preservation"));
 			return;
 		}
 		if (this.literalSurface) this.source.reconcileFormattedChange(markdown, view.state.doc.attrs[sourceAttribute]);
@@ -59909,12 +60159,23 @@ var InkKitEditor = class InkKitEditor {
 	}
 	/** Reports a refused edit to the facade call that made it, or else to `events.error`. */
 	refuse(error) {
+		this.diagnostics.capture({
+			kind: "error",
+			code: error.code,
+			...error.code === "preservation" ? { reason: diagnosticReason(error) } : {}
+		});
 		if (this.call) this.call.refusal ??= error;
 		else this.events.error?.(error);
 	}
 	/** Reports a failure no call is waiting for. */
 	report(error) {
-		this.events.error?.(coded(error));
+		const failure = coded(error);
+		this.diagnostics.capture({
+			kind: "error",
+			code: failure.code,
+			...failure.code === "preservation" ? { reason: diagnosticReason(failure) } : {}
+		});
+		this.events.error?.(failure);
 	}
 	/** Runs a facade method for something the person did, such as a shortcut. Its failure goes to
 	*  `events.error`, unless a host call such as `keyDown` is waiting for it. */
@@ -59930,6 +60191,93 @@ var InkKitEditor = class InkKitEditor {
 	get composing() {
 		return this.literalSurface ? this.source.composing : this.editor.ctx.get(editorViewCtx).composing;
 	}
+	diagnosticState() {
+		const view = this.editor?.ctx.get(editorViewCtx);
+		const literal = this.source && this.literalSurface;
+		return {
+			ready: this.ready,
+			revision: this.session.revision,
+			generation: this.session.generation,
+			format: this.document.format,
+			mode: literal ? "source" : "formatted",
+			editable: this.writable,
+			composing: Boolean(literal ? this.source.composing : view?.composing),
+			pending: Boolean(this.pasteController?.pending),
+			...view ? { selection: literal ? {
+				from: this.source.element.selectionStart,
+				to: this.source.element.selectionEnd
+			} : {
+				from: view.state.selection.from,
+				to: view.state.selection.to
+			} } : {}
+		};
+	}
+	/** Starts or clears content-free local tracing. Disabled by default. */
+	setDiagnosticsEnabled(enabled) {
+		this.assertAlive();
+		if (typeof enabled !== "boolean") throw invalidArgument("enabled must be a boolean");
+		this.diagnostics.setEnabled(enabled, this.root, this.editor.ctx);
+	}
+	/** Reads diagnostics without serializing the document or requiring an editable surface. */
+	diagnosticReport() {
+		this.assertAlive();
+		let presentation;
+		if (this.diagnostics.enabled) try {
+			const view = this.editor.ctx.get(editorViewCtx);
+			const literal = this.literalSurface;
+			const selection = view.state.selection;
+			const dom = literal ? this.source.element : view.domAtPos(selection.from).node;
+			const element = dom.nodeType === 1 ? dom : dom.parentElement ?? view.dom;
+			const window = this.root.ownerDocument.defaultView;
+			const style = window.getComputedStyle(element);
+			const fontFamily = style.fontFamily.slice(0, 160).replace(/[^\p{L}\p{N} ,"'_-]/gu, "");
+			const type = selection.$from.parent.type.name;
+			const block = literal ? "literal" : type === "paragraph" ? "paragraph" : type === "heading" ? "heading" : type === "code_block" ? "code" : "other";
+			const markNames = [
+				"strong",
+				"emphasis",
+				"inlineCode",
+				"strike_through",
+				"link",
+				"highlight"
+			];
+			const marks = literal ? [] : (view.state.storedMarks ?? selection.$from.marks()).slice(0, 12).map((mark) => markNames.find((name) => name === mark.type.name) ?? "other");
+			const bounds = literal ? void 0 : view.coordsAtPos(selection.from);
+			presentation = {
+				fontFamily,
+				fontSize: diagnosticNumber(Number.parseFloat(style.fontSize)),
+				fontWeight: diagnosticNumber(style.fontWeight === "normal" ? 400 : style.fontWeight === "bold" ? 700 : Number.parseFloat(style.fontWeight)),
+				fontStyle: style.fontStyle === "normal" || style.fontStyle === "italic" || style.fontStyle === "oblique" ? style.fontStyle : "other",
+				...!literal && type === "heading" && [
+					1,
+					2,
+					3,
+					4,
+					5,
+					6
+				].includes(selection.$from.parent.attrs.level) ? { headingLevel: selection.$from.parent.attrs.level } : {},
+				...style.lineHeight !== "normal" ? { lineHeight: diagnosticNumber(Number.parseFloat(style.lineHeight)) } : {},
+				block,
+				marks,
+				caretColor: /^(?:rgba?\([\d.,% ]+\)|#[\da-f]{3,8}|auto|transparent|currentcolor)$/i.test(style.caretColor) ? style.caretColor.slice(0, 80) : "other",
+				...bounds ? { caret: {
+					left: diagnosticNumber(bounds.left),
+					top: diagnosticNumber(bounds.top),
+					right: diagnosticNumber(bounds.right),
+					bottom: diagnosticNumber(bounds.bottom)
+				} } : {},
+				viewport: {
+					width: diagnosticNumber(window.innerWidth),
+					height: diagnosticNumber(window.innerHeight)
+				},
+				scroll: {
+					left: diagnosticNumber(this.geometry.container.scrollLeft),
+					top: diagnosticNumber(this.geometry.container.scrollTop)
+				}
+			};
+		} catch {}
+		return this.diagnostics.report(presentation);
+	}
 	/** The formats the host offered at mount, in its order, with what saving each promises. */
 	get formats() {
 		this.assertAlive();
@@ -60263,6 +60611,7 @@ var InkKitEditor = class InkKitEditor {
 	*  throws `destroyed`. */
 	async destroy() {
 		if (this.destroyed) return;
+		this.diagnostics.destroy(this.editor.ctx);
 		this.destroyed = true;
 		this.clipboard.clear();
 		this.ready = false;
@@ -60971,12 +61320,46 @@ var InkKitEditor = class InkKitEditor {
 			"viewport",
 			"headings",
 			"navigateHeading",
-			"destroy"
+			"destroy",
+			"setDiagnosticsEnabled",
+			"diagnosticReport"
 		]) {
 			const method = InkKitEditor.prototype[name];
 			Object.defineProperty(InkKitEditor.prototype, name, {
 				value(...args) {
-					return this.facadeCall(() => method.apply(this, args));
+					if (name === "setDiagnosticsEnabled" || name === "diagnosticReport") return method.apply(this, args);
+					if (!this.diagnostics.enabled) return this.facadeCall(() => method.apply(this, args));
+					const operation = diagnosticOperation(name);
+					this.diagnostics.capture({
+						kind: "operation",
+						phase: "begin",
+						operation
+					});
+					const success = (value) => {
+						this.diagnostics.capture({
+							kind: "operation",
+							phase: "success",
+							operation
+						});
+						return value;
+					};
+					const refused = (error) => {
+						const failure = coded(error);
+						this.diagnostics.capture({
+							kind: "operation",
+							phase: "refused",
+							operation,
+							code: failure.code,
+							...failure.code === "preservation" ? { reason: diagnosticReason(failure) } : {}
+						});
+						throw failure;
+					};
+					try {
+						const result = this.facadeCall(() => method.apply(this, args));
+						return result instanceof Promise ? result.then(success, refused) : success(result);
+					} catch (error) {
+						return refused(error);
+					}
 				},
 				writable: true,
 				configurable: true

package/dist/chunks/{highlight-CqtvWKCp.js → highlight-D3LQRB1-.js}

@@ -1,4 +1,4 @@
-import { a as Decoration, c as PluginKey, d as __toESM, i as $prose, o as DecorationSet, s as Plugin, u as __commonJSMin } from "./core-CisgnAp-.js";
+import { a as Decoration, c as PluginKey, d as __toESM, i as $prose, o as DecorationSet, s as Plugin, u as __commonJSMin } from "./core-fEBASTpF.js";
 //#region node_modules/.pnpm/highlight.js@11.11.2/node_modules/highlight.js/es/languages/arduino.js
 /** @type LanguageFn */
 function cPlusPlus(hljs) {

package/dist/core.d.ts

@@ -3,3 +3,4 @@ export type { EditorEvents, EditorOptions, TextInputPreferences, CommandState, E
 export { InkKitError } from './types.js';
 export type { DocumentFormat, TextDocumentFormat, TextDocumentInput, RichTextDocumentInput, TextDocumentSnapshot, RichTextDocumentSnapshot, RichTextDocument, RichTextBlock, RichTextListItem, RichTextTableCell, RichTextInline, RichTextMark, FormatLoss, FormatLossCode, ConvertedDocument, FormatPromise, OfferedFormat, EditorLabels, Heading, TableCommand, TableOptions, BlockMoveDirection, DocumentContext, DocumentInput, DocumentSnapshot, DocumentVersion, EditorErrorCode, ImageAdapter, ImageImportContext, WikiLinkReference, WikiLinkAdapter, FileReference, ClientPoint, FileContext, FilePresentation, FileAdapter, CapturedImage, PortableImage, ClipboardInput, ClipboardOutput, ClipboardScope, ClipboardImage, ClipboardDiagram, PrintableDocument, PrintableWarning, TextRange, ReadableTextSnapshot, TextRect, ViewportInsets, ViewportOptions, ViewportSnapshot, } from './types.js';
 export type { SlashMenuOptions, SlashCommandName, SlashCommand } from './types.js';
+export type { DiagnosticReport, DiagnosticEvent, DiagnosticState, DiagnosticPresentation, } from './diagnostics.js';

package/dist/core.js

@@ -1,2 +1,2 @@
-import { r as InkKitError, t as InkKitEditor } from "./chunks/core-CisgnAp-.js";
+import { r as InkKitError, t as InkKitEditor } from "./chunks/core-fEBASTpF.js";
 export { InkKitEditor, InkKitError };

package/dist/diagnostics.d.ts

@@ -0,0 +1,94 @@
+import { type DocumentFormat, type EditorErrorCode } from './types.js';
+/** Content-free editor counters and input guards. */
+export type DiagnosticState = {
+    ready: boolean;
+    revision: number;
+    generation?: number;
+    format: DocumentFormat;
+    mode: 'formatted' | 'source';
+    editable: boolean;
+    composing: boolean;
+    pending: boolean;
+    selection?: {
+        from: number;
+        to: number;
+    };
+};
+/** Closed categories, never raw browser input, method arguments or error messages. */
+export type DiagnosticEvent = {
+    sequence: number;
+    elapsedMs: number;
+    kind: 'input' | 'composition' | 'focus' | 'selection' | 'operation' | 'preservation' | 'error' | 'enabled';
+    state: DiagnosticState;
+    phase?: 'before' | 'after' | 'start' | 'end' | 'in' | 'out' | 'begin' | 'success' | 'refused';
+    input?: 'text' | 'composition' | 'delete' | 'paste' | 'drop' | 'history' | 'format' | 'other';
+    operation?: 'snapshot' | 'edit' | 'history' | 'load' | 'configuration' | 'output' | 'selection' | 'lifecycle' | 'other';
+    code?: EditorErrorCode;
+    path?: 'unchanged' | 'local' | 'regions' | 'whole';
+    reason?: 'matching-budget' | 'source-location' | 'reopen-mismatch' | 'parse-refusal' | 'unexpected';
+};
+/** Declared CSS configuration and geometry, measured only when a report is requested. */
+export type DiagnosticPresentation = {
+    fontFamily: string;
+    fontSize: number;
+    fontWeight: number;
+    fontStyle: 'normal' | 'italic' | 'oblique' | 'other';
+    headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
+    lineHeight?: number;
+    block: 'paragraph' | 'heading' | 'code' | 'other' | 'literal';
+    marks: ('strong' | 'emphasis' | 'inlineCode' | 'strike_through' | 'link' | 'highlight' | 'other')[];
+    caretColor: string;
+    caret?: {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    };
+    viewport: {
+        width: number;
+        height: number;
+    };
+    scroll: {
+        left: number;
+        top: number;
+    };
+};
+/** An opt-in local report. Disabling diagnostics clears all retained events and the incident. */
+export type DiagnosticReport = {
+    schemaVersion: 1;
+    enabled: boolean;
+    sessionId: string;
+    state: DiagnosticState;
+    events: DiagnosticEvent[];
+    incident?: {
+        triggerSequence: number;
+        events: DiagnosticEvent[];
+        tail: DiagnosticEvent[];
+    };
+    presentation?: DiagnosticPresentation;
+};
+type Detail = Omit<DiagnosticEvent, 'sequence' | 'elapsedMs' | 'state'>;
+export declare function observePreservation(ctx: object, observer?: (detail: Detail) => void): void;
+export declare function tracePreservation(ctx: object, detail: Detail): void;
+export declare class Diagnostics {
+    private readonly state;
+    enabled: boolean;
+    private sessionId;
+    private started;
+    private sequence;
+    private events;
+    private incident?;
+    private dispose?;
+    private latestState;
+    private currentState;
+    capture(detail: Detail): void;
+    constructor(state: () => DiagnosticState);
+    setEnabled(enabled: boolean, root: HTMLElement, ctx: object): void;
+    private record;
+    report(presentation?: DiagnosticPresentation): DiagnosticReport;
+    destroy(ctx: object): void;
+}
+export declare function diagnosticOperation(name: string): DiagnosticEvent['operation'];
+export declare const diagnosticNumber: (value: number) => number;
+export declare function diagnosticReason(error: unknown): DiagnosticEvent['reason'];
+export {};

package/dist/editor.d.ts

@@ -1,3 +1,4 @@
+import { type DiagnosticReport } from './diagnostics.js';
 import type { SlashMenuOptions } from './types.js';
 import { InkKitError, type ClientPoint, type DocumentFormat, type DocumentInput, type DocumentSnapshot, type ConvertedDocument, type TextDocumentFormat, type ImageAdapter, type FileAdapter, type WikiLinkAdapter, type ClipboardInput, type ClipboardOutput, type ClipboardScope, type DocumentVersion, type PrintableDocument, type TextRange, type ReadableTextSnapshot, type TextRect, type ViewportOptions, type ViewportSnapshot, type EditorLabels, type Heading, type TableCommand, type TableOptions, type BlockMoveDirection, type OfferedFormat } from './types.js';
 /** An inline format that `CaretState` can report. */
@@ -157,6 +158,7 @@ export declare const editorEvents: readonly ["changed", "commandStateChanged", "
 export declare class InkKitEditor<F extends DocumentFormat = TextDocumentFormat> {
     private readonly options;
     private editor;
+    private readonly diagnostics;
     private readonly document;
     private readonly history;
     private readonly text;
@@ -248,6 +250,11 @@ export declare class InkKitEditor<F extends DocumentFormat = TextDocumentFormat>
      *  `events.error`, unless a host call such as `keyDown` is waiting for it. */
     private forPerson;
     private get composing();
+    private diagnosticState;
+    /** Starts or clears content-free local tracing. Disabled by default. */
+    setDiagnosticsEnabled(enabled: boolean): void;
+    /** Reads diagnostics without serializing the document or requiring an editable surface. */
+    diagnosticReport(): DiagnosticReport;
     /** The formats the host offered at mount, in its order, with what saving each promises. */
     get formats(): readonly OfferedFormat[];
     /** Whether the person can edit. A read-only editor still permits selection, copying and find. */

package/dist/index.js

@@ -1,4 +1,4 @@
-import { n as registerDiagram, r as InkKitError, t as InkKitEditor } from "./chunks/core-CisgnAp-.js";
+import { n as registerDiagram, r as InkKitError, t as InkKitEditor } from "./chunks/core-fEBASTpF.js";
 //#region node_modules/.pnpm/dompurify@3.4.17/node_modules/dompurify/dist/purify.es.mjs
 /*! @license DOMPurify 3.4.17 | (c) Cure53 and other contributors | Released under the Apache license 2.0 and Mozilla Public License 2.0 | github.com/cure53/DOMPurify/blob/3.4.17/LICENSE */
 function _OverloadYield(e, d) {

package/dist/style.css

@@ -376,6 +376,22 @@
   white-space: normal;
 }
 
+/* A file presentation with `layout: 'fill'` takes the column's width instead of its label's. */
+.inkkit-root
+  .ProseMirror
+  .inkkit-image.inkkit-file[data-inkkit-file-layout='fill'] {
+  display: block;
+  width: 100%;
+}
+.inkkit-root .ProseMirror .inkkit-file[data-inkkit-file-activation='card'] {
+  cursor: pointer;
+}
+.inkkit-root
+  .ProseMirror
+  .inkkit-file[data-inkkit-file-activation='card']:hover {
+  background: var(--_inkkit-code-bg);
+}
+
 .inkkit-root .ProseMirror .inkkit-file-footer {
   display: flex;
   flex-wrap: wrap;
@@ -1103,6 +1119,7 @@
 /* One ring for every control InkKit draws; the editing surfaces can be set apart. */
 .inkkit-root button:focus-visible,
 .inkkit-root .inkkit-image-handle:focus-visible,
+.inkkit-root .inkkit-file[data-inkkit-file-activation='card']:focus-visible,
 .inkkit-root .inkkit-file audio:focus-visible,
 .inkkit-root .inkkit-file video:focus-visible {
   outline: var(--inkkit-focus-width, 2px) solid

package/dist/types.d.ts

@@ -212,7 +212,14 @@ export type FilePresentation = {
     label?: string;
     mimeType?: string;
 } | {
-    kind: 'file' | 'missing';
+    kind: 'file';
+    label?: string;
+    /** `'fill'` stretches the card to the full width of the column. */
+    layout?: 'fill';
+    /** `'card'` makes the whole card the one control that calls `FileAdapter.open`. */
+    activation?: 'card';
+} | {
+    kind: 'missing';
     label?: string;
 } | {
     kind: 'error';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aicayzer/inkkit",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "A preserving Markdown editor for offline web views and the web",
   "license": "MIT",
   "type": "module",