@olenbetong/appframe-ds 1.5.0 → 1.6.1

package/src/mdi/controller.ts

@@ -1,656 +1,656 @@
-import mitt, { type Emitter } from "mitt";
-
-import type { MdiHost } from "./host.js";
-import { panelId } from "./ids.js";
-import {
-	dockPopoutGroups,
-	isLayoutEmpty,
-	listGridGroups,
-	missingRequiredDocuments,
-	placementFor,
-	pruneLayout,
-} from "./layoutRestore.js";
-import { layoutSpecToLayout, resolveLocked } from "./layoutSpec.js";
-import { layoutStore as defaultLayoutStore, type MdiLayoutStore } from "./layoutStore.js";
-import { resolveClosable, resolveTitle, resolveType } from "./registry.js";
-import type {
-	MdiApi,
-	MdiCloseOptions,
-	MdiConfirmCloseResult,
-	MdiDocumentInfo,
-	MdiDocumentOptions,
-	MdiDocumentState,
-	MdiDocumentTypes,
-	MdiEvents,
-	MdiLayout,
-	MdiLayoutSpec,
-	MdiOpenOptions,
-	MdiParams,
-} from "./types.js";
-
-export type MdiControllerOptions = {
-	/** Storage key within the article. Without it nothing is restored or saved. */
-	id?: string;
-	layoutVersion: string | number;
-	defaultLayout: MdiLayoutSpec;
-	/** Save every layout change automatically. Off: only `saveLayout()` writes, but a saved layout is still restored on load. */
-	persist: boolean;
-	popoutUrl: string;
-	confirmClose: (document: MdiDocumentInfo) => Promise<MdiConfirmCloseResult>;
-};
-
-type InternalDocument = MdiDocumentState & { dirty: boolean };
-
-type StoreEvents = MdiEvents & { change: undefined };
-
-/**
- * Owns the documents of one `Mdi`: the registry lookup, the open/close/dirty
- * lifecycle, restore and persistence. Talks to dockview through the narrow
- * `MdiHost` interface so it can be tested without a DOM. The React layer is a thin
- * shell around it; `MdiProvider` creates one and `useMdi()` hands it out.
- */
-export class MdiController implements MdiApi {
-	#types: MdiDocumentTypes;
-	#store: MdiLayoutStore;
-	#documents = new Map<string, InternalDocument>();
-	#guards = new Map<string, MdiDocumentOptions>();
-	#emitter: Emitter<StoreEvents> = mitt<StoreEvents>();
-	#host: MdiHost | undefined;
-	#hostDisposables: (() => void)[] = [];
-	#options: MdiControllerOptions | undefined;
-	#activeId: string | undefined;
-	#infoCache = new Map<string, MdiDocumentInfo>();
-	#listCache: MdiDocumentInfo[] | undefined;
-	#emptyList: MdiDocumentInfo[] = [];
-	#initialized = false;
-	#applying = false;
-	#generation = 0;
-
-	constructor(types: MdiDocumentTypes, store: MdiLayoutStore = defaultLayoutStore) {
-		this.#types = types;
-		this.#store = store;
-	}
-
-	getTypes(): MdiDocumentTypes {
-		return this.#types;
-	}
-
-	setTypes(types: MdiDocumentTypes) {
-		this.#types = types;
-	}
-
-	setOptions(options: MdiControllerOptions) {
-		this.#options = options;
-	}
-
-	get isAttached(): boolean {
-		return this.#host !== undefined;
-	}
-
-	/* ---------------------------------------------------------------- host */
-
-	attach(host: MdiHost) {
-		this.detach();
-		this.#host = host;
-		this.#hostDisposables = [
-			host.onDidActivePanelChange((id) => this.#setActive(id)),
-			host.onDidRemovePanel((id) => this.#handleRemoved(id)),
-			host.onDidLayoutChange(() => {
-				if (this.#applying) return;
-				this.#emitter.emit("layoutChange", undefined);
-				this.#scheduleSave();
-			}),
-		];
-	}
-
-	detach() {
-		for (let dispose of this.#hostDisposables) dispose();
-		this.#hostDisposables = [];
-		this.#host = undefined;
-		this.#initialized = false;
-		this.#generation += 1;
-	}
-
-	/**
-	 * Restores the persisted layout (dropping documents the app no longer wants) or
-	 * applies the default one, then makes sure every fixed pane is present.
-	 */
-	async initialize(): Promise<void> {
-		let options = this.#requireOptions();
-		let generation = ++this.#generation;
-		let key = this.#storageKey();
-		let layout: MdiLayout | undefined;
-
-		if (key) {
-			await this.#store.loaded;
-			if (generation !== this.#generation) return;
-
-			let persisted = this.#store.get(key, options.layoutVersion);
-
-			if (persisted) {
-				layout = await this.#resolvePersisted(persisted);
-				if (generation !== this.#generation) return;
-			}
-		}
-
-		this.#applyRestoredOrDefault(layout);
-	}
-
-	/* ---------------------------------------------------------- documents */
-
-	openDocument<P extends MdiParams = MdiParams>(options: MdiOpenOptions<P>): string {
-		let host = this.#requireHost();
-		let definition = resolveType(this.#types, options.type);
-		let key = definition.singleton ? undefined : options.key;
-		let id = panelId(options.type, key);
-		let existing = this.#documents.get(id);
-
-		if (existing) {
-			let changed = false;
-
-			if (options.params) {
-				existing.params = { ...options.params };
-				changed = true;
-			}
-
-			if (options.title !== undefined && options.title !== existing.title) {
-				existing.title = options.title;
-				host.getPanel(id)?.setTitle(options.title);
-				this.#emitter.emit("titleChange", { id, title: options.title });
-				changed = true;
-			}
-
-			if (changed) {
-				this.#invalidate(id);
-				this.#scheduleSave();
-			}
-
-			if (!options.inactive) {
-				this.activate(id);
-			}
-
-			return id;
-		}
-
-		let params: MdiParams = { ...options.params };
-		let title = options.title ?? resolveTitle(definition, options.type, params, key);
-
-		this.#documents.set(id, {
-			type: options.type,
-			key,
-			params,
-			title,
-			closable: resolveClosable(definition, options.closable),
-			dirty: false,
-		});
-
-		host.addPanel({ id, title, position: options.position, inactive: options.inactive });
-		this.#invalidate(id);
-		this.#emitter.emit("open", this.getDocument(id)!);
-		this.#scheduleSave();
-
-		return id;
-	}
-
-	activate(id: string) {
-		this.#host?.getPanel(id)?.setActive();
-	}
-
-	async close(id: string, options: MdiCloseOptions = {}): Promise<boolean> {
-		let document = this.#documents.get(id);
-
-		if (!document) {
-			return false;
-		}
-
-		if (!options.force) {
-			if (!document.closable) {
-				return false;
-			}
-
-			let guards = this.#guards.get(id);
-
-			if (guards?.onClosing && !(await guards.onClosing())) {
-				return false;
-			}
-
-			if (document.dirty) {
-				let result = await this.#requireOptions().confirmClose(this.getDocument(id)!);
-
-				if (result === "cancel") {
-					return false;
-				}
-
-				if (result === "save") {
-					let saved = guards?.onSave ? await guards.onSave() : true;
-
-					if (!saved) {
-						return false;
-					}
-				}
-			}
-		}
-
-		// The document may have gone away while a guard was pending.
-		if (!this.#documents.has(id)) {
-			return true;
-		}
-
-		let panel = this.#host?.getPanel(id);
-
-		if (panel) {
-			panel.close();
-		} else {
-			this.#handleRemoved(id, true);
-		}
-
-		return true;
-	}
-
-	async closeByKey(key: string, options: MdiCloseOptions = { force: true }): Promise<void> {
-		let ids = [...this.#documents.entries()].filter(([, document]) => document.key === key).map(([id]) => id);
-
-		for (let id of ids) {
-			await this.close(id, options);
-		}
-	}
-
-	async closeAll(type?: string): Promise<boolean> {
-		let ids = [...this.#documents.entries()]
-			.filter(([, document]) => document.closable && (type === undefined || document.type === type))
-			.map(([id]) => id);
-
-		for (let id of ids) {
-			if (this.#documents.has(id) && !(await this.close(id))) {
-				return false;
-			}
-		}
-
-		return true;
-	}
-
-	setTitle(id: string, title: string) {
-		let document = this.#documents.get(id);
-
-		if (!document || document.title === title) {
-			return;
-		}
-
-		document.title = title;
-		this.#host?.getPanel(id)?.setTitle(title);
-		this.#invalidate(id);
-		this.#emitter.emit("titleChange", { id, title });
-		this.#scheduleSave();
-	}
-
-	setDirty(id: string, dirty: boolean) {
-		let document = this.#documents.get(id);
-
-		if (!document || document.dirty === dirty) {
-			return;
-		}
-
-		document.dirty = dirty;
-		this.#invalidate(id);
-		this.#emitter.emit("dirtyChange", { id, dirty });
-	}
-
-	getActive = (): MdiDocumentInfo | undefined => {
-		return this.#activeId ? this.getDocument(this.#activeId) : undefined;
-	};
-
-	getDocument = (id: string): MdiDocumentInfo | undefined => {
-		let cached = this.#infoCache.get(id);
-
-		if (cached) {
-			return cached;
-		}
-
-		let document = this.#documents.get(id);
-
-		if (!document) {
-			return undefined;
-		}
-
-		let info: MdiDocumentInfo = { ...document, id, isActive: id === this.#activeId };
-		this.#infoCache.set(id, info);
-
-		return info;
-	};
-
-	/** Every open document, in insertion order. Referentially stable until something changes. */
-	getDocumentsSnapshot = (): MdiDocumentInfo[] => {
-		if (!this.#listCache) {
-			let list = [...this.#documents.keys()].map((id) => this.getDocument(id)!);
-			this.#listCache = list.length === 0 ? this.#emptyList : list;
-		}
-
-		return this.#listCache;
-	};
-
-	getDocuments(type?: string): MdiDocumentInfo[] {
-		let all = this.getDocumentsSnapshot();
-		return type === undefined ? [...all] : all.filter((document) => document.type === type);
-	}
-
-	hasDirty(): boolean {
-		for (let document of this.#documents.values()) {
-			if (document.dirty) return true;
-		}
-
-		return false;
-	}
-
-	async popout(id: string): Promise<boolean> {
-		let host = this.#requireHost();
-		return host.addPopoutGroup(id, this.#requireOptions().popoutUrl);
-	}
-
-	getWindow(id: string): Window {
-		return this.#host?.getPanel(id)?.getWindow() ?? globalThis.window;
-	}
-
-	panelId(type: string, key?: string): string {
-		let definition = this.#types[type];
-		return panelId(type, definition?.singleton ? undefined : key);
-	}
-
-	/* -------------------------------------------------------------- guards */
-
-	/** Registers the close guards of a mounted document component. Returns the unregister function. */
-	registerGuards(id: string, guards: MdiDocumentOptions): () => void {
-		this.#guards.set(id, guards);
-
-		return () => {
-			// Another instance may already have registered for the same id (React remounts).
-			if (this.#guards.get(id) === guards) {
-				this.#guards.delete(id);
-			}
-		};
-	}
-
-	/* -------------------------------------------------------------- events */
-
-	subscribe<K extends keyof MdiEvents>(event: K, handler: (event: MdiEvents[K]) => void): () => void {
-		this.#emitter.on(event, handler);
-		return () => this.#emitter.off(event, handler);
-	}
-
-	/** Fires on every change of the document list, a document, or the active document. For `useSyncExternalStore`. */
-	subscribeStore = (handler: () => void): (() => void) => {
-		this.#emitter.on("change", handler);
-		return () => this.#emitter.off("change", handler);
-	};
-
-	/* -------------------------------------------------------------- layout */
-
-	getLayout(): MdiLayout | undefined {
-		if (!this.#host || !this.#options) {
-			return undefined;
-		}
-
-		let documents: Record<string, MdiDocumentState> = {};
-
-		for (let [id, document] of this.#documents) {
-			let { dirty: _dirty, ...state } = document;
-			documents[id] = state;
-		}
-
-		return {
-			format: 1,
-			layoutVersion: this.#options.layoutVersion,
-			documents,
-			dockview: this.#host.toJSON(),
-		};
-	}
-
-	async saveLayout(): Promise<MdiLayout | undefined> {
-		let key = this.#storageKey();
-		let layout = this.getLayout();
-
-		if (key && layout) {
-			await this.#store.setNow(key, layout);
-		}
-
-		return layout;
-	}
-
-	async loadLayout(layout?: MdiLayout): Promise<void> {
-		let options = this.#requireOptions();
-		let key = this.#storageKey();
-		let source = layout ?? (key ? this.#store.get(key, options.layoutVersion) : undefined);
-		let resolved = source ? await this.#resolvePersisted(source) : undefined;
-
-		this.#applyRestoredOrDefault(resolved);
-	}
-
-	async resetLayout(): Promise<void> {
-		let key = this.#storageKey();
-
-		if (key) {
-			await this.#store.remove(key);
-		}
-
-		this.#applyRestoredOrDefault(undefined);
-	}
-
-	/* ------------------------------------------------------------ internal */
-
-	#requireHost(): MdiHost {
-		if (!this.#host) {
-			throw new Error("Mdi: no dock is mounted yet. Open documents after <Mdi> has rendered.");
-		}
-
-		return this.#host;
-	}
-
-	#requireOptions(): MdiControllerOptions {
-		if (!this.#options) {
-			throw new Error("Mdi: the controller has no options. Render <Mdi> inside the provider first.");
-		}
-
-		return this.#options;
-	}
-
-	#storageKey(): string | undefined {
-		let id = this.#options?.id;
-		return id ? this.#store.key(id) : undefined;
-	}
-
-	#defaultLayout(): MdiLayout {
-		let options = this.#requireOptions();
-		return layoutSpecToLayout(options.defaultLayout, this.#types, options.layoutVersion);
-	}
-
-	#applyRestoredOrDefault(layout: MdiLayout | undefined) {
-		let options = this.#requireOptions();
-
-		if (layout && !isLayoutEmpty(layout)) {
-			try {
-				this.#applyLayout(layout);
-			} catch (error) {
-				console.warn("Mdi: could not apply the saved layout, falling back to the default.", error);
-				layout = undefined;
-			}
-		} else {
-			layout = undefined;
-		}
-
-		if (!layout) {
-			layout = this.#defaultLayout();
-			this.#applyLayout(layout);
-		}
-
-		this.#initialized = true;
-		this.#addMissingRequired(options.defaultLayout, layout);
-	}
-
-	/** Re-docks popouts, runs the `restore` resolvers and drops what they reject. */
-	async #resolvePersisted(persisted: MdiLayout): Promise<MdiLayout> {
-		let layout: MdiLayout = { ...persisted, dockview: dockPopoutGroups(persisted.dockview) };
-		let keep = new Set<string>();
-		let documents: Record<string, MdiDocumentState> = {};
-
-		await Promise.all(
-			Object.entries(layout.documents).map(async ([id, document]) => {
-				let definition = this.#types[document.type];
-
-				if (!definition) {
-					console.warn(`Mdi: dropping document "${id}", its type is no longer registered.`);
-					return;
-				}
-
-				try {
-					let result = definition.restore
-						? await definition.restore({ key: document.key, params: document.params })
-						: true;
-
-					if (result === false) {
-						return;
-					}
-
-					let state: MdiDocumentState = { ...document, params: { ...document.params } };
-
-					if (typeof result === "object") {
-						if (result.params) state.params = { ...result.params };
-						if (result.title !== undefined) state.title = result.title;
-					}
-
-					keep.add(id);
-					documents[id] = state;
-				} catch (error) {
-					console.warn(`Mdi: dropping document "${id}", restore failed.`, error);
-				}
-			}),
-		);
-
-		let pruned = pruneLayout({ ...layout, documents }, keep);
-
-		for (let [id, document] of Object.entries(pruned.documents)) {
-			let panel = pruned.dockview.panels[id];
-			if (panel) panel.title = document.title;
-		}
-
-		return pruned;
-	}
-
-	#applyLayout(layout: MdiLayout) {
-		let host = this.#requireHost();
-
-		this.#applying = true;
-
-		try {
-			this.#documents.clear();
-			this.#guards.clear();
-
-			for (let [id, document] of Object.entries(layout.documents)) {
-				this.#documents.set(id, { ...document, params: { ...document.params }, dirty: false });
-			}
-
-			host.fromJSON(structuredClone(layout.dockview));
-
-			// dockview's fromJSON reduces `locked` to a boolean, which still allows drops beside
-			// the group; put the stricter value back.
-			for (let group of listGridGroups(layout.dockview)) {
-				if (group.locked === "no-drop-target") host.getGroup(group.id)?.setLocked("no-drop-target");
-			}
-
-			// Drop anything dockview did not accept, so the two sides agree.
-			for (let id of this.#documents.keys()) {
-				if (!host.getPanel(id)) this.#documents.delete(id);
-			}
-		} finally {
-			this.#applying = false;
-		}
-
-		this.#activeId = host.getActivePanelId();
-		this.#invalidate();
-		this.#emitter.emit("activeChange", this.getActive());
-		this.#emitter.emit("layoutChange", undefined);
-	}
-
-	/** Fixed panes added to the default layout after a layout was saved are missing from it; put them back. */
-	#addMissingRequired(spec: MdiLayoutSpec, layout: MdiLayout) {
-		let host = this.#requireHost();
-
-		for (let document of missingRequiredDocuments(spec, this.#types, layout)) {
-			let existing = new Set(this.#documents.keys());
-			let { position, groupSpec } = placementFor(spec, document.id, this.#types, existing);
-			let id = this.openDocument({
-				type: document.type,
-				key: document.key,
-				params: document.params,
-				title: document.title,
-				closable: false,
-				position,
-				inactive: true,
-			});
-			let panel = host.getPanel(id);
-
-			if (panel && groupSpec && position.direction !== "within" && panel.group.panelCount === 1) {
-				let locked = resolveLocked(groupSpec);
-				if (groupSpec.hideHeader) panel.group.setHeaderHidden(true);
-				if (locked) panel.group.setLocked(locked);
-			}
-		}
-	}
-
-	#handleRemoved(id: string, force = false) {
-		if (this.#applying) return;
-
-		// dockview reports removals while moving panels between groups too; only a panel
-		// that is really gone counts as closed.
-		if (!force && this.#host?.getPanel(id)) return;
-
-		let info = this.getDocument(id);
-
-		if (!info) return;
-
-		this.#documents.delete(id);
-		this.#guards.delete(id);
-
-		if (this.#activeId === id) {
-			this.#activeId = undefined;
-		}
-
-		this.#invalidate();
-		this.#emitter.emit("close", info);
-		this.#scheduleSave();
-	}
-
-	#setActive(id: string | undefined) {
-		if (id === this.#activeId) return;
-
-		let previous = this.#activeId;
-		this.#activeId = id;
-
-		if (previous) this.#infoCache.delete(previous);
-		if (id) this.#infoCache.delete(id);
-		this.#listCache = undefined;
-
-		this.#emitter.emit("change", undefined);
-		this.#emitter.emit("activeChange", this.getActive());
-	}
-
-	#invalidate(id?: string) {
-		if (id === undefined) {
-			this.#infoCache.clear();
-		} else {
-			this.#infoCache.delete(id);
-		}
-
-		this.#listCache = undefined;
-		this.#emitter.emit("change", undefined);
-	}
-
-	#scheduleSave() {
-		if (!this.#initialized || this.#applying || !this.#options?.persist) return;
-
-		let key = this.#storageKey();
-		let layout = this.getLayout();
-
-		if (key && layout) {
-			this.#store.set(key, layout);
-		}
-	}
-}
+import mitt, { type Emitter } from "mitt";
+
+import type { MdiHost } from "./host.js";
+import { panelId } from "./ids.js";
+import {
+	dockPopoutGroups,
+	isLayoutEmpty,
+	listGridGroups,
+	missingRequiredDocuments,
+	placementFor,
+	pruneLayout,
+} from "./layoutRestore.js";
+import { layoutSpecToLayout, resolveLocked } from "./layoutSpec.js";
+import { layoutStore as defaultLayoutStore, type MdiLayoutStore } from "./layoutStore.js";
+import { resolveClosable, resolveTitle, resolveType } from "./registry.js";
+import type {
+	MdiApi,
+	MdiCloseOptions,
+	MdiConfirmCloseResult,
+	MdiDocumentInfo,
+	MdiDocumentOptions,
+	MdiDocumentState,
+	MdiDocumentTypes,
+	MdiEvents,
+	MdiLayout,
+	MdiLayoutSpec,
+	MdiOpenOptions,
+	MdiParams,
+} from "./types.js";
+
+export type MdiControllerOptions = {
+	/** Storage key within the article. Without it nothing is restored or saved. */
+	id?: string;
+	layoutVersion: string | number;
+	defaultLayout: MdiLayoutSpec;
+	/** Save every layout change automatically. Off: only `saveLayout()` writes, but a saved layout is still restored on load. */
+	persist: boolean;
+	popoutUrl: string;
+	confirmClose: (document: MdiDocumentInfo) => Promise<MdiConfirmCloseResult>;
+};
+
+type InternalDocument = MdiDocumentState & { dirty: boolean };
+
+type StoreEvents = MdiEvents & { change: undefined };
+
+/**
+ * Owns the documents of one `Mdi`: the registry lookup, the open/close/dirty
+ * lifecycle, restore and persistence. Talks to dockview through the narrow
+ * `MdiHost` interface so it can be tested without a DOM. The React layer is a thin
+ * shell around it; `MdiProvider` creates one and `useMdi()` hands it out.
+ */
+export class MdiController implements MdiApi {
+	#types: MdiDocumentTypes;
+	#store: MdiLayoutStore;
+	#documents = new Map<string, InternalDocument>();
+	#guards = new Map<string, MdiDocumentOptions>();
+	#emitter: Emitter<StoreEvents> = mitt<StoreEvents>();
+	#host: MdiHost | undefined;
+	#hostDisposables: (() => void)[] = [];
+	#options: MdiControllerOptions | undefined;
+	#activeId: string | undefined;
+	#infoCache = new Map<string, MdiDocumentInfo>();
+	#listCache: MdiDocumentInfo[] | undefined;
+	#emptyList: MdiDocumentInfo[] = [];
+	#initialized = false;
+	#applying = false;
+	#generation = 0;
+
+	constructor(types: MdiDocumentTypes, store: MdiLayoutStore = defaultLayoutStore) {
+		this.#types = types;
+		this.#store = store;
+	}
+
+	getTypes(): MdiDocumentTypes {
+		return this.#types;
+	}
+
+	setTypes(types: MdiDocumentTypes) {
+		this.#types = types;
+	}
+
+	setOptions(options: MdiControllerOptions) {
+		this.#options = options;
+	}
+
+	get isAttached(): boolean {
+		return this.#host !== undefined;
+	}
+
+	/* ---------------------------------------------------------------- host */
+
+	attach(host: MdiHost) {
+		this.detach();
+		this.#host = host;
+		this.#hostDisposables = [
+			host.onDidActivePanelChange((id) => this.#setActive(id)),
+			host.onDidRemovePanel((id) => this.#handleRemoved(id)),
+			host.onDidLayoutChange(() => {
+				if (this.#applying) return;
+				this.#emitter.emit("layoutChange", undefined);
+				this.#scheduleSave();
+			}),
+		];
+	}
+
+	detach() {
+		for (let dispose of this.#hostDisposables) dispose();
+		this.#hostDisposables = [];
+		this.#host = undefined;
+		this.#initialized = false;
+		this.#generation += 1;
+	}
+
+	/**
+	 * Restores the persisted layout (dropping documents the app no longer wants) or
+	 * applies the default one, then makes sure every fixed pane is present.
+	 */
+	async initialize(): Promise<void> {
+		let options = this.#requireOptions();
+		let generation = ++this.#generation;
+		let key = this.#storageKey();
+		let layout: MdiLayout | undefined;
+
+		if (key) {
+			await this.#store.loaded;
+			if (generation !== this.#generation) return;
+
+			let persisted = this.#store.get(key, options.layoutVersion);
+
+			if (persisted) {
+				layout = await this.#resolvePersisted(persisted);
+				if (generation !== this.#generation) return;
+			}
+		}
+
+		this.#applyRestoredOrDefault(layout);
+	}
+
+	/* ---------------------------------------------------------- documents */
+
+	openDocument<P extends MdiParams = MdiParams>(options: MdiOpenOptions<P>): string {
+		let host = this.#requireHost();
+		let definition = resolveType(this.#types, options.type);
+		let key = definition.singleton ? undefined : options.key;
+		let id = panelId(options.type, key);
+		let existing = this.#documents.get(id);
+
+		if (existing) {
+			let changed = false;
+
+			if (options.params) {
+				existing.params = { ...options.params };
+				changed = true;
+			}
+
+			if (options.title !== undefined && options.title !== existing.title) {
+				existing.title = options.title;
+				host.getPanel(id)?.setTitle(options.title);
+				this.#emitter.emit("titleChange", { id, title: options.title });
+				changed = true;
+			}
+
+			if (changed) {
+				this.#invalidate(id);
+				this.#scheduleSave();
+			}
+
+			if (!options.inactive) {
+				this.activate(id);
+			}
+
+			return id;
+		}
+
+		let params: MdiParams = { ...options.params };
+		let title = options.title ?? resolveTitle(definition, options.type, params, key);
+
+		this.#documents.set(id, {
+			type: options.type,
+			key,
+			params,
+			title,
+			closable: resolveClosable(definition, options.closable),
+			dirty: false,
+		});
+
+		host.addPanel({ id, title, position: options.position, inactive: options.inactive });
+		this.#invalidate(id);
+		this.#emitter.emit("open", this.getDocument(id)!);
+		this.#scheduleSave();
+
+		return id;
+	}
+
+	activate(id: string) {
+		this.#host?.getPanel(id)?.setActive();
+	}
+
+	async close(id: string, options: MdiCloseOptions = {}): Promise<boolean> {
+		let document = this.#documents.get(id);
+
+		if (!document) {
+			return false;
+		}
+
+		if (!options.force) {
+			if (!document.closable) {
+				return false;
+			}
+
+			let guards = this.#guards.get(id);
+
+			if (guards?.onClosing && !(await guards.onClosing())) {
+				return false;
+			}
+
+			if (document.dirty) {
+				let result = await this.#requireOptions().confirmClose(this.getDocument(id)!);
+
+				if (result === "cancel") {
+					return false;
+				}
+
+				if (result === "save") {
+					let saved = guards?.onSave ? await guards.onSave() : true;
+
+					if (!saved) {
+						return false;
+					}
+				}
+			}
+		}
+
+		// The document may have gone away while a guard was pending.
+		if (!this.#documents.has(id)) {
+			return true;
+		}
+
+		let panel = this.#host?.getPanel(id);
+
+		if (panel) {
+			panel.close();
+		} else {
+			this.#handleRemoved(id, true);
+		}
+
+		return true;
+	}
+
+	async closeByKey(key: string, options: MdiCloseOptions = { force: true }): Promise<void> {
+		let ids = [...this.#documents.entries()].filter(([, document]) => document.key === key).map(([id]) => id);
+
+		for (let id of ids) {
+			await this.close(id, options);
+		}
+	}
+
+	async closeAll(type?: string): Promise<boolean> {
+		let ids = [...this.#documents.entries()]
+			.filter(([, document]) => document.closable && (type === undefined || document.type === type))
+			.map(([id]) => id);
+
+		for (let id of ids) {
+			if (this.#documents.has(id) && !(await this.close(id))) {
+				return false;
+			}
+		}
+
+		return true;
+	}
+
+	setTitle(id: string, title: string) {
+		let document = this.#documents.get(id);
+
+		if (!document || document.title === title) {
+			return;
+		}
+
+		document.title = title;
+		this.#host?.getPanel(id)?.setTitle(title);
+		this.#invalidate(id);
+		this.#emitter.emit("titleChange", { id, title });
+		this.#scheduleSave();
+	}
+
+	setDirty(id: string, dirty: boolean) {
+		let document = this.#documents.get(id);
+
+		if (!document || document.dirty === dirty) {
+			return;
+		}
+
+		document.dirty = dirty;
+		this.#invalidate(id);
+		this.#emitter.emit("dirtyChange", { id, dirty });
+	}
+
+	getActive = (): MdiDocumentInfo | undefined => {
+		return this.#activeId ? this.getDocument(this.#activeId) : undefined;
+	};
+
+	getDocument = (id: string): MdiDocumentInfo | undefined => {
+		let cached = this.#infoCache.get(id);
+
+		if (cached) {
+			return cached;
+		}
+
+		let document = this.#documents.get(id);
+
+		if (!document) {
+			return undefined;
+		}
+
+		let info: MdiDocumentInfo = { ...document, id, isActive: id === this.#activeId };
+		this.#infoCache.set(id, info);
+
+		return info;
+	};
+
+	/** Every open document, in insertion order. Referentially stable until something changes. */
+	getDocumentsSnapshot = (): MdiDocumentInfo[] => {
+		if (!this.#listCache) {
+			let list = [...this.#documents.keys()].map((id) => this.getDocument(id)!);
+			this.#listCache = list.length === 0 ? this.#emptyList : list;
+		}
+
+		return this.#listCache;
+	};
+
+	getDocuments(type?: string): MdiDocumentInfo[] {
+		let all = this.getDocumentsSnapshot();
+		return type === undefined ? [...all] : all.filter((document) => document.type === type);
+	}
+
+	hasDirty(): boolean {
+		for (let document of this.#documents.values()) {
+			if (document.dirty) return true;
+		}
+
+		return false;
+	}
+
+	async popout(id: string): Promise<boolean> {
+		let host = this.#requireHost();
+		return host.addPopoutGroup(id, this.#requireOptions().popoutUrl);
+	}
+
+	getWindow(id: string): Window {
+		return this.#host?.getPanel(id)?.getWindow() ?? globalThis.window;
+	}
+
+	panelId(type: string, key?: string): string {
+		let definition = this.#types[type];
+		return panelId(type, definition?.singleton ? undefined : key);
+	}
+
+	/* -------------------------------------------------------------- guards */
+
+	/** Registers the close guards of a mounted document component. Returns the unregister function. */
+	registerGuards(id: string, guards: MdiDocumentOptions): () => void {
+		this.#guards.set(id, guards);
+
+		return () => {
+			// Another instance may already have registered for the same id (React remounts).
+			if (this.#guards.get(id) === guards) {
+				this.#guards.delete(id);
+			}
+		};
+	}
+
+	/* -------------------------------------------------------------- events */
+
+	subscribe<K extends keyof MdiEvents>(event: K, handler: (event: MdiEvents[K]) => void): () => void {
+		this.#emitter.on(event, handler);
+		return () => this.#emitter.off(event, handler);
+	}
+
+	/** Fires on every change of the document list, a document, or the active document. For `useSyncExternalStore`. */
+	subscribeStore = (handler: () => void): (() => void) => {
+		this.#emitter.on("change", handler);
+		return () => this.#emitter.off("change", handler);
+	};
+
+	/* -------------------------------------------------------------- layout */
+
+	getLayout(): MdiLayout | undefined {
+		if (!this.#host || !this.#options) {
+			return undefined;
+		}
+
+		let documents: Record<string, MdiDocumentState> = {};
+
+		for (let [id, document] of this.#documents) {
+			let { dirty: _dirty, ...state } = document;
+			documents[id] = state;
+		}
+
+		return {
+			format: 1,
+			layoutVersion: this.#options.layoutVersion,
+			documents,
+			dockview: this.#host.toJSON(),
+		};
+	}
+
+	async saveLayout(): Promise<MdiLayout | undefined> {
+		let key = this.#storageKey();
+		let layout = this.getLayout();
+
+		if (key && layout) {
+			await this.#store.setNow(key, layout);
+		}
+
+		return layout;
+	}
+
+	async loadLayout(layout?: MdiLayout): Promise<void> {
+		let options = this.#requireOptions();
+		let key = this.#storageKey();
+		let source = layout ?? (key ? this.#store.get(key, options.layoutVersion) : undefined);
+		let resolved = source ? await this.#resolvePersisted(source) : undefined;
+
+		this.#applyRestoredOrDefault(resolved);
+	}
+
+	async resetLayout(): Promise<void> {
+		let key = this.#storageKey();
+
+		if (key) {
+			await this.#store.remove(key);
+		}
+
+		this.#applyRestoredOrDefault(undefined);
+	}
+
+	/* ------------------------------------------------------------ internal */
+
+	#requireHost(): MdiHost {
+		if (!this.#host) {
+			throw new Error("Mdi: no dock is mounted yet. Open documents after <Mdi> has rendered.");
+		}
+
+		return this.#host;
+	}
+
+	#requireOptions(): MdiControllerOptions {
+		if (!this.#options) {
+			throw new Error("Mdi: the controller has no options. Render <Mdi> inside the provider first.");
+		}
+
+		return this.#options;
+	}
+
+	#storageKey(): string | undefined {
+		let id = this.#options?.id;
+		return id ? this.#store.key(id) : undefined;
+	}
+
+	#defaultLayout(): MdiLayout {
+		let options = this.#requireOptions();
+		return layoutSpecToLayout(options.defaultLayout, this.#types, options.layoutVersion);
+	}
+
+	#applyRestoredOrDefault(layout: MdiLayout | undefined) {
+		let options = this.#requireOptions();
+
+		if (layout && !isLayoutEmpty(layout)) {
+			try {
+				this.#applyLayout(layout);
+			} catch (error) {
+				console.warn("Mdi: could not apply the saved layout, falling back to the default.", error);
+				layout = undefined;
+			}
+		} else {
+			layout = undefined;
+		}
+
+		if (!layout) {
+			layout = this.#defaultLayout();
+			this.#applyLayout(layout);
+		}
+
+		this.#initialized = true;
+		this.#addMissingRequired(options.defaultLayout, layout);
+	}
+
+	/** Re-docks popouts, runs the `restore` resolvers and drops what they reject. */
+	async #resolvePersisted(persisted: MdiLayout): Promise<MdiLayout> {
+		let layout: MdiLayout = { ...persisted, dockview: dockPopoutGroups(persisted.dockview) };
+		let keep = new Set<string>();
+		let documents: Record<string, MdiDocumentState> = {};
+
+		await Promise.all(
+			Object.entries(layout.documents).map(async ([id, document]) => {
+				let definition = this.#types[document.type];
+
+				if (!definition) {
+					console.warn(`Mdi: dropping document "${id}", its type is no longer registered.`);
+					return;
+				}
+
+				try {
+					let result = definition.restore
+						? await definition.restore({ key: document.key, params: document.params })
+						: true;
+
+					if (result === false) {
+						return;
+					}
+
+					let state: MdiDocumentState = { ...document, params: { ...document.params } };
+
+					if (typeof result === "object") {
+						if (result.params) state.params = { ...result.params };
+						if (result.title !== undefined) state.title = result.title;
+					}
+
+					keep.add(id);
+					documents[id] = state;
+				} catch (error) {
+					console.warn(`Mdi: dropping document "${id}", restore failed.`, error);
+				}
+			}),
+		);
+
+		let pruned = pruneLayout({ ...layout, documents }, keep);
+
+		for (let [id, document] of Object.entries(pruned.documents)) {
+			let panel = pruned.dockview.panels[id];
+			if (panel) panel.title = document.title;
+		}
+
+		return pruned;
+	}
+
+	#applyLayout(layout: MdiLayout) {
+		let host = this.#requireHost();
+
+		this.#applying = true;
+
+		try {
+			this.#documents.clear();
+			this.#guards.clear();
+
+			for (let [id, document] of Object.entries(layout.documents)) {
+				this.#documents.set(id, { ...document, params: { ...document.params }, dirty: false });
+			}
+
+			host.fromJSON(structuredClone(layout.dockview));
+
+			// dockview's fromJSON reduces `locked` to a boolean, which still allows drops beside
+			// the group; put the stricter value back.
+			for (let group of listGridGroups(layout.dockview)) {
+				if (group.locked === "no-drop-target") host.getGroup(group.id)?.setLocked("no-drop-target");
+			}
+
+			// Drop anything dockview did not accept, so the two sides agree.
+			for (let id of this.#documents.keys()) {
+				if (!host.getPanel(id)) this.#documents.delete(id);
+			}
+		} finally {
+			this.#applying = false;
+		}
+
+		this.#activeId = host.getActivePanelId();
+		this.#invalidate();
+		this.#emitter.emit("activeChange", this.getActive());
+		this.#emitter.emit("layoutChange", undefined);
+	}
+
+	/** Fixed panes added to the default layout after a layout was saved are missing from it; put them back. */
+	#addMissingRequired(spec: MdiLayoutSpec, layout: MdiLayout) {
+		let host = this.#requireHost();
+
+		for (let document of missingRequiredDocuments(spec, this.#types, layout)) {
+			let existing = new Set(this.#documents.keys());
+			let { position, groupSpec } = placementFor(spec, document.id, this.#types, existing);
+			let id = this.openDocument({
+				type: document.type,
+				key: document.key,
+				params: document.params,
+				title: document.title,
+				closable: false,
+				position,
+				inactive: true,
+			});
+			let panel = host.getPanel(id);
+
+			if (panel && groupSpec && position.direction !== "within" && panel.group.panelCount === 1) {
+				let locked = resolveLocked(groupSpec);
+				if (groupSpec.hideHeader) panel.group.setHeaderHidden(true);
+				if (locked) panel.group.setLocked(locked);
+			}
+		}
+	}
+
+	#handleRemoved(id: string, force = false) {
+		if (this.#applying) return;
+
+		// dockview reports removals while moving panels between groups too; only a panel
+		// that is really gone counts as closed.
+		if (!force && this.#host?.getPanel(id)) return;
+
+		let info = this.getDocument(id);
+
+		if (!info) return;
+
+		this.#documents.delete(id);
+		this.#guards.delete(id);
+
+		if (this.#activeId === id) {
+			this.#activeId = undefined;
+		}
+
+		this.#invalidate();
+		this.#emitter.emit("close", info);
+		this.#scheduleSave();
+	}
+
+	#setActive(id: string | undefined) {
+		if (id === this.#activeId) return;
+
+		let previous = this.#activeId;
+		this.#activeId = id;
+
+		if (previous) this.#infoCache.delete(previous);
+		if (id) this.#infoCache.delete(id);
+		this.#listCache = undefined;
+
+		this.#emitter.emit("change", undefined);
+		this.#emitter.emit("activeChange", this.getActive());
+	}
+
+	#invalidate(id?: string) {
+		if (id === undefined) {
+			this.#infoCache.clear();
+		} else {
+			this.#infoCache.delete(id);
+		}
+
+		this.#listCache = undefined;
+		this.#emitter.emit("change", undefined);
+	}
+
+	#scheduleSave() {
+		if (!this.#initialized || this.#applying || !this.#options?.persist) return;
+
+		let key = this.#storageKey();
+		let layout = this.getLayout();
+
+		if (key && layout) {
+			this.#store.set(key, layout);
+		}
+	}
+}