obsidian-dev-utils 101.5.0 → 101.7.0

package/dist/lib/cjs/obsidian/plugin/plugin.d.cts

@@ -9,13 +9,16 @@
 import type { Component, IconName } from 'obsidian' with { 'resolution-mode': 'import' };
 import type { Promisable } from 'type-fest' with { 'resolution-mode': 'import' };
 import { Plugin } from 'obsidian';
+import type { PluginConflict, PluginDependency } from '../components/plugin-gate-component.cjs';
 import type { TranslationsMap } from '../i18n/i18n.cjs';
+import type { PluginApiDeclaration } from './plugin-api.cjs';
 import type { PluginEventMap, PluginEventSource } from './plugin-event-source.cjs';
 import { CommandHandlerComponent } from '../command-handlers/command-handler-component.cjs';
 import { AbortSignalComponent } from '../components/abort-signal-component.cjs';
 import { AsyncErrorHandlerComponent } from '../components/async-error-handler-component.cjs';
 import { ConsoleDebugComponent } from '../components/console-debug-component.cjs';
 import { PluginContextComponent } from '../components/plugin-context-component.cjs';
+import { PluginGateComponent } from '../components/plugin-gate-component.cjs';
 import { PluginNoticeComponent } from '../components/plugin-notice-component.cjs';
 import { PluginSettingsComponentBase } from '../components/plugin-settings-component.cjs';
 import { ResourceLockComponent } from '../resource-lock.cjs';
@@ -90,6 +93,22 @@ export declare abstract class PluginBase extends PluginBase_base implements Plug
      * @param value - Plugin context component.
      */
     protected set pluginContextComponent(value: PluginContextComponent);
+    /**
+     * Gets the gate holding the plugin's feature surface up or down.
+     *
+     * Reach for it from a settings tab to render the overlap banner for a
+     * {@link obsidian/components/plugin-gate-component!PluginConflictSeverity.Warn} conflict — the one
+     * banner the library cannot place itself, because a running plugin builds its own settings tab.
+     *
+     * @returns The plugin gate component.
+     */
+    protected get pluginGateComponent(): PluginGateComponent;
+    /**
+     * Sets the plugin gate component.
+     *
+     * @param value - The plugin gate component.
+     */
+    protected set pluginGateComponent(value: PluginGateComponent);
     /**
      * Gets plugin notice component.
      *
@@ -128,13 +147,22 @@ export declare abstract class PluginBase extends PluginBase_base implements Plug
      */
     protected set resourceLockComponent(value: ResourceLockComponent);
     private readonly components;
-    private readonly wrapperComponent;
+    private gatedWrapperComponent;
+    private lifecycleEventPayload;
+    private readonly universalWrapperComponent;
     /**
      * Adds a child component.
      *
-     * The child is added to an internal wrapper component, which {@link onload} attaches and loads
-     * before wiring anything up. So a child added during {@link onloadImpl} is loaded immediately,
-     * children-first, and is usable by the time this method returns.
+     * The child is added to the internal wrapper holding the subclass's own surface, which {@link onload}
+     * creates and loads before calling {@link onloadImpl}. So a child added during {@link onloadImpl} is
+     * loaded immediately, children-first, and is usable by the time this method returns.
+     *
+     * That wrapper is torn down and rebuilt whenever the gate closes and opens again — a dependency declared
+     * by {@link getPluginDependencies} going away and coming back, or a conflict declared by
+     * {@link getPluginConflicts} appearing and being resolved — so a child added here lives exactly as long
+     * as the plugin's feature surface does. Adding one while the surface is down is still legitimate — it is
+     * queued and loaded when the surface next comes up, the way {@link ComponentEx.addChild} already queues
+     * a child added to a not-yet-loaded component.
      *
      * @typeParam TComponent - The type of component to add.
      * @param component - The component instance to add.
@@ -157,6 +185,15 @@ export declare abstract class PluginBase extends PluginBase_base implements Plug
      * Do NOT override this method. Override {@link onloadImpl} instead.
      */
     onload(): Promise<void>;
+    /**
+     * Called when the plugin is unloaded.
+     *
+     * Announces the departure on `app.workspace` so anything depending on this plugin learns of it at the
+     * moment it happens, rather than discovering it later through behavior that quietly stopped.
+     *
+     * Do NOT override this method; put teardown on a component instead, which unloads with the plugin.
+     */
+    onunload(): void;
     /**
      * Removes a child component.
      *
@@ -184,6 +221,62 @@ export declare abstract class PluginBase extends PluginBase_base implements Plug
      * @returns The icon, or `''` for no icon.
      */
     protected getNotebookNavigatorMenuSubmenuIcon(): IconName;
+    /**
+     * Provides the APIs this plugin exposes to other plugins.
+     *
+     * Override in subclass to publish one. The default publishes none. Called after {@link onloadImpl}, so a
+     * declaration may reference anything it created; the returned declarations are published through
+     * `publishPluginApi` and revoked when the plugin's feature surface unloads.
+     *
+     * Returning a LIST rather than a single API is deliberate: the registry supports several contract
+     * versions published side by side, which is how a provider ships a breaking `2.0.0` without stranding
+     * consumers still pinned to `^1`.
+     *
+     * Every declaration here is published BEFORE the `obsidian-dev-utils:plugin-loaded` broadcast, which is
+     * what lets a listener call these APIs the moment it hears that event.
+     *
+     * @returns The API declarations.
+     */
+    protected getPluginApis(): PluginApiDeclaration[];
+    /**
+     * Provides the plugins this one refuses, or warns about, running beside.
+     *
+     * Override in subclass to declare an overlap. The default declares none.
+     *
+     * A `Block` conflict is the mirror image of a dependency: while a conflicting plugin is enabled at a
+     * conflicting version, {@link onloadImpl} does not run at all and the plugin registers nothing. Declare
+     * it when both plugins acting on the same operation damages the vault — there is no reliable way to win
+     * that race, because whichever plugin loaded first keeps a hand on the wheel, so refusing deterministically
+     * beats competing unpredictably. A `Warn` conflict declares an overlap that is merely annoying, such as a
+     * duplicated command: both plugins keep running and the user is told.
+     *
+     * Unlike a dependency, a conflicting plugin need not publish anything — it is detected by reading its
+     * installed version, which is the only thing about another plugin that reads the same regardless of load
+     * order.
+     *
+     * @returns The declared conflicts.
+     */
+    protected getPluginConflicts(): PluginConflict[];
+    /**
+     * Provides the plugins this one cannot work without.
+     *
+     * Override in subclass to declare a mandatory dependency. The default declares none, and such a plugin
+     * loads exactly as it always has.
+     *
+     * A declared dependency is MANDATORY, unlike the offer `PluginSuggestionComponent` makes: while one is
+     * missing, disabled, or too old, {@link onloadImpl} does not run at all and the plugin registers nothing
+     * — no commands, no handlers, no patches. It stays enabled in Obsidian's list rather than disabling
+     * itself, because the enabled set is the user's to change, and it explains itself through a notice and a
+     * settings banner that installs the missing plugin in one click. The load completes the moment the
+     * dependency arrives, with no restart.
+     *
+     * A dependency must publish an API through `publishPluginApi`, which is what makes its presence,
+     * absence, version and departure all observable through one mechanism. A plugin with nothing to expose
+     * can publish an empty API purely so it can be depended upon.
+     *
+     * @returns The declared dependencies.
+     */
+    protected getPluginDependencies(): PluginDependency[];
     /**
      * Called during {@link onload} to wire plugin-specific child components.
      *
@@ -204,7 +297,43 @@ export declare abstract class PluginBase extends PluginBase_base implements Plug
      * @param key - The key of the component to store.
      * @param value - The component to store.
      */
+    /**
+     * Adds a component to the universal tier, which outlives any dependency.
+     *
+     * Private on purpose: only this class decides what is universal. A subclass adding one of its own goes
+     * through {@link addChild} and lands in the gated tier, where it belongs.
+     *
+     * @typeParam TComponent - The type of component to add.
+     * @param component - The component instance to add.
+     * @returns The added component.
+     */
+    private addUniversalChild;
+    /**
+     * Announces on `app.workspace` that this plugin is loaded and its APIs are callable.
+     */
+    private broadcastLoaded;
+    /**
+     * Announces on `app.workspace` that this plugin's surface has gone away.
+     *
+     * Silent unless a loaded broadcast is outstanding, so the two events stay paired: a plugin that never
+     * got past its dependency gate never announced itself, and must not announce a departure either.
+     */
+    private broadcastUnloaded;
+    /**
+     * Builds and loads the subclass's feature surface, then publishes its APIs and announces itself.
+     *
+     * NOT idempotent, deliberately. `PluginGateComponent` owns the up/down state machine and calls
+     * this only on a real transition; a second guard here would be a second copy of that state, which is the
+     * kind of duplicate that drifts.
+     *
+     * @returns A {@link Promise} that resolves once the surface is loaded and the broadcast has been made.
+     */
+    private loadFeatureSurface;
     private setComponent;
+    /**
+     * Tears the subclass's feature surface down, leaving the universal components running.
+     */
+    private unloadFeatureSurface;
 }
 /**
  * Reloads the specified plugin by disabling and then re-enabling it.

package/dist/lib/cjs/obsidian/plugin/settings-migration-api.cjs

@@ -0,0 +1,141 @@
+/*
+THIS IS A GENERATED/BUNDLED FILE BY ESBUILD
+if you want to view the source, please visit the github repository of this plugin
+*/
+
+(function () {
+function ensureBrowserProcess() {
+  const browserProcess = {
+    browser: true,
+    cwd() {
+      return '/';
+    },
+    env: {},
+    platform: 'android'
+  };
+
+  // eslint-disable-next-line obsidianmd/no-global-this, unicorn/no-unnecessary-global-this -- Must stay `globalThis`-qualified: in the emitted banner a bare `process` is a free identifier, so reading it where the host has none throws a ReferenceError instead of yielding `undefined`. That is the very case this function exists to handle.
+  const existingProcess = globalThis.process;
+
+  if (!existingProcess) {
+    // eslint-disable-next-line obsidianmd/no-global-this -- Actively use globalThis.
+    globalThis.process = browserProcess;
+    return;
+  }
+
+  if (existingProcess.versions?.node) {
+    return;
+  }
+
+  const existingProcessRecord = existingProcess;
+
+  for (const [key, value] of Object.entries(browserProcess)) {
+    existingProcessRecord[key] ??= value;
+  }
+
+  existingProcessRecord['browser'] = true;
+}
+
+function keepName($unknown) {
+  return $unknown;
+}
+
+(function initCjs() {
+  // eslint-disable-next-line obsidianmd/no-global-this -- Actively use globalThis.
+  const globalThisRecord = globalThis;
+  globalThisRecord['__name'] ??= keepName;
+  const originalRequire = require;
+  if (originalRequire && !originalRequire.__isPatched) {
+    // eslint-disable-next-line no-global-assign, no-implicit-globals -- We need to patch the `require()` function.
+    require = Object.assign(
+      (id) => requirePatched(id),
+      originalRequire,
+      {
+        __isPatched: true
+      }
+    );
+  }
+
+  globalThisRecord['__extractDefault'] ??= extractDefault;
+
+  ensureBrowserProcess();
+
+  function extractDefault(module) {
+    return module && module.__esModule && 'default' in module ? module.default : module;
+  }
+
+  const OBSIDIAN_BUILT_IN_MODULE_NAMES = new Set([
+  '@codemirror/autocomplete',
+  '@codemirror/collab',
+  '@codemirror/commands',
+  '@codemirror/language',
+  '@codemirror/lint',
+  '@codemirror/search',
+  '@codemirror/state',
+  '@codemirror/text',
+  '@codemirror/view',
+  '@lezer/common',
+  '@lezer/highlight',
+  '@lezer/lr',
+  'obsidian']
+  );
+
+  const DEPRECATED_OBSIDIAN_BUILT_IN_MODULE_NAMES = new Set([
+  '@codemirror/closebrackets',
+  '@codemirror/comment',
+  '@codemirror/fold',
+  '@codemirror/gutter',
+  '@codemirror/highlight',
+  '@codemirror/history',
+  '@codemirror/matchbrackets',
+  '@codemirror/panel',
+  '@codemirror/rangeset',
+  '@codemirror/rectangular-selection',
+  '@codemirror/stream-parser',
+  '@codemirror/tooltip']
+  );
+
+  function requirePatched(id) {
+    if (OBSIDIAN_BUILT_IN_MODULE_NAMES.has(id) || DEPRECATED_OBSIDIAN_BUILT_IN_MODULE_NAMES.has(id)) {
+      return originalRequire?.(id);
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-deprecated, obsidianmd/no-global-this  -- Need access to app. Actively use globalThis.
+    if (globalThis.app.isMobile) {
+      if (id === 'process' || id === 'node:process') {
+        // eslint-disable-next-line no-console -- Valid usage.
+        console.debug(`The most likely you can safely ignore this error. Module not found: ${id}. Fake process object is returned instead.`);
+
+        return process;
+      }
+    } else {
+      const module = originalRequire?.(id);
+      if (module) {
+        return extractDefault(module);
+      }
+    }
+
+    // eslint-disable-next-line no-console -- Valid usage.
+    console.debug(`The most likely you can safely ignore this error. Module not found: ${id}. Empty object is returned instead.`);
+    return {};
+  }
+})();
+})();
+
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var settings_migration_api_exports = {};
+module.exports = __toCommonJS(settings_migration_api_exports);
+//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFsiLi4vLi4vLi4vLi4vLi4vc3JjL29ic2lkaWFuL3BsdWdpbi9zZXR0aW5ncy1taWdyYXRpb24tYXBpLnRzIl0sCiAgInNvdXJjZXNDb250ZW50IjogWyIvKipcbiAqIEBmaWxlXG4gKlxuICogVGhlIGdlbmVyaWMgaGFsZiBvZiBhIHNldHRpbmdzIEhBTkRPVkVSIGNvbnRyYWN0OiBvbmUgcGx1Z2luIG9mZmVycyBhbm90aGVyIHRoZSBzZXR0aW5ncyBpdCB1c2VkIHRvIG93bixcbiAqIGFuZCB0aGUgcGx1Z2luIHRoYXQgb3ducyB0aGVtIG5vdyBkZWNpZGVzIHdoYXQgdG8gZG8gd2l0aCB0aGUgb2ZmZXIuXG4gKlxuICogVGhlIHNoYXBlIGJlbG93IGlzIGRlbGliZXJhdGVseSB0aGUgKmVudmVsb3BlKiBhbmQgbm90aGluZyBlbHNlLiBBIGhhbmRvdmVyIGhhcyB0aHJlZSBwYXJ0cywgYW5kIG9ubHkgb25lXG4gKiBvZiB0aGVtIGlzIGdlbmVyaWM6XG4gKlxuICogLSBUaGUgKiplbnZlbG9wZSoqIFx1MjAxNCBhIGBtaWdyYXRlU2V0dGluZ3NgIGNhbGwsIHdobyBpcyBwcm9wb3NpbmcsIGFuZCB3aGV0aGVyIHRoZSB1c2VyIGFwcGxpZWQgaXQuIElkZW50aWNhbFxuICogICBmb3IgZXZlcnkgcGFpciBvZiBwbHVnaW5zLCBzbyBpdCBsaXZlcyBoZXJlLlxuICogLSBUaGUgKipwYXlsb2FkKiogXHUyMDE0IHdoaWNoIHNldHRpbmdzIGFyZSBiZWluZyBwcm9wb3NlZC4gRW50aXJlbHkgdGhlIHBhaXIncyBvd24gYnVzaW5lc3MsIHNvIGl0IHN0YXlzIGEgdHlwZVxuICogICBwYXJhbWV0ZXIgYW5kIGlzIG5ldmVyIG5hbWVkIGhlcmUuXG4gKiAtIFRoZSAqKnByb3ZpZGVyJ3MgaWRlbnRpdHkqKiBcdTIwMTQgaXRzIHBsdWdpbiBpZCBhbmQgZGlzcGxheSBuYW1lLiBBbHNvIHRoZSBwYWlyJ3Mgb3duIGJ1c2luZXNzLCBhbmQgbm90XG4gKiAgIHNvbWV0aGluZyB0aGlzIGxpYnJhcnkgaGFzIGFueSBzdGFuZGluZyB0byBvd24uXG4gKlxuICogV2h5IGl0IGlzIGRlY2xhcmVkIHJhdGhlciB0aGFuIGltcG9ydGVkLiBBIHByb3ZpZGVyIGlzIHR5cGljYWxseSBhbiBPYnNpZGlhbiAqcGx1Z2luKiByZXBvLCBub3QgYW4gbnBtXG4gKiBwYWNrYWdlLCBzbyBhIGNvbnN1bWVyIGhhcyBub3RoaW5nIHRvIGRlcGVuZCBvbiBhbmQgaGFuZC13cml0ZXMgaXRzIG93biBjb3B5IG9mIHRoZSBjb250cmFjdC4gRml2ZSBjb3BpZXNcbiAqIG9mIG9uZSBjb250cmFjdCB3aXRoIG5vIGNvbXBpbGVyIGxpbmsgYmV0d2VlbiB0aGVtIG1lYW5zIGRyaWZ0IGlzIFNJTEVOVCBcdTIwMTQgZXZlcnkgY29weSBzdGlsbCBjb21waWxlcyBhbmRcbiAqIHRoZSBoYW5kb3ZlciBmYWlscyBhdCBydW50aW1lIGluc3RlYWQuIERlY2xhcmluZyB0aGUgZW52ZWxvcGUgaGVyZSBnaXZlcyBib3RoIGVuZHMgb25lIGRlY2xhcmF0aW9uIHRvXG4gKiBjb21waWxlIGFnYWluc3Q7IGB3YXRjaFBsdWdpbkFwaWAgc3RpbGwgbmVnb3RpYXRlcyB0aGUgdmVyc2lvbiBhdCBydW50aW1lLCBiZWNhdXNlIHRoZSB0d28gZW5kcyBzaGlwXG4gKiBpbmRlcGVuZGVudGx5IGFuZCBhbHdheXMgd2lsbC5cbiAqXG4gKiBUaGUgcHJvdmlkZXIgcHVibGlzaGVzIGl0OlxuICpcbiAqIGBgYHRzXG4gKiBwdWJsaXNoUGx1Z2luQXBpPFNldHRpbmdzTWlncmF0aW9uQXBpPE15TWlncmF0YWJsZVNldHRpbmdzPj4oe1xuICogICBhcGk6IHRoaXMuc2V0dGluZ3NNaWdyYXRpb25BcGksXG4gKiAgIGFwaVZlcnNpb246ICcxLjAuMCcsXG4gKiAgIGNvbnRyYWN0OiB7IG1pZ3JhdGVTZXR0aW5nczoge30gfSxcbiAqICAgcGx1Z2luOiB0aGlzXG4gKiB9KTtcbiAqIGBgYFxuICpcbiAqIFRoZSBjb25zdW1lciByZWFjaGVzIGl0IHRocm91Z2gge0BsaW5rIG9ic2lkaWFuL2NvbXBvbmVudHMvc2V0dGluZ3MtbWlncmF0aW9uLWNvbXBvbmVudCFTZXR0aW5nc01pZ3JhdGlvbkNvbXBvbmVudH0sXG4gKiB3aGljaCBvd25zIHRoZSB3aG9sZSBvZmZlci1hbmQtcmV0aXJlIGRhbmNlLlxuICovXG5cbi8qKlxuICogUGFyYW1ldGVycyBmb3Ige0BsaW5rIFNldHRpbmdzTWlncmF0aW9uQXBpLm1pZ3JhdGVTZXR0aW5nc30uXG4gKlxuICogQHR5cGVQYXJhbSBUTWlncmF0YWJsZVNldHRpbmdzIC0gVGhlIHNldHRpbmdzIHRoZSBwcm9wb3NpbmcgcGx1Z2luIG1heSBoYW5kIG92ZXIuXG4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgTWlncmF0ZVNldHRpbmdzUGFyYW1zPFRNaWdyYXRhYmxlU2V0dGluZ3MgZXh0ZW5kcyBvYmplY3Q+IHtcbiAgLyoqXG4gICAqIFRoZSB2YWx1ZXMgdGhlIHByb3Bvc2luZyBwbHVnaW4gb2ZmZXJzLlxuICAgKlxuICAgKiBDb252ZW50aW9uYWxseSBldmVyeSBtZW1iZXIgaXMgb3B0aW9uYWwsIHNvIGEgcGx1Z2luIHByb3Bvc2VzIG9ubHkgd2hhdCBpdCBhY3R1YWxseSBoZWxkIGFuZCBhIHZhbHVlIHRoZVxuICAgKiBwcm92aWRlciBhbHJlYWR5IG93bnMgaXMgbmV2ZXIgb3ZlcndyaXR0ZW4gYnkgYSBkZWZhdWx0IG5vYm9keSBjaG9zZS4gVGhhdCBjb252ZW50aW9uIGJlbG9uZ3MgdG8gdGhlIHBhaXIsXG4gICAqIHRob3VnaCBcdTIwMTQgdGhpcyB0eXBlIGltcG9zZXMgb25seSB0aGUgZW52ZWxvcGUuXG4gICAqL1xuICByZWFkb25seSBwcm9wb3NlZFNldHRpbmdzOiBUTWlncmF0YWJsZVNldHRpbmdzO1xuXG4gIC8qKlxuICAgKiBUaGUgYG1hbmlmZXN0LmlkYCBvZiB0aGUgcGx1Z2luIG1ha2luZyB0aGUgcHJvcG9zYWwsIHNvIHRoZSBwcm92aWRlcidzIGRpYWxvZyBjYW4gc2F5IHdob3NlIHNldHRpbmdzXG4gICAqIHRoZXNlIGFyZS5cbiAgICovXG4gIHJlYWRvbmx5IHNvdXJjZVBsdWdpbklkOiBzdHJpbmc7XG59XG5cbi8qKlxuICogVGhlIG91dGNvbWUgb2Yge0BsaW5rIFNldHRpbmdzTWlncmF0aW9uQXBpLm1pZ3JhdGVTZXR0aW5nc30uXG4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgTWlncmF0ZVNldHRpbmdzUmVzdWx0IHtcbiAgLyoqXG4gICAqIFdoZXRoZXIgdGhlIHVzZXIgYXBwcm92ZWQgdGhlIG1pZ3JhdGlvbi5cbiAgICpcbiAgICogYGZhbHNlYCBtZWFucyB0aGV5IGNhbmNlbGxlZCBhbmQgbm90aGluZyB3YXMgd3JpdHRlbiwgc28gdGhlIHByb3Bvc2luZyBwbHVnaW4gbXVzdCBOT1QgcmVjb3JkIHRoZVxuICAgKiBtaWdyYXRpb24gYXMgZG9uZSBcdTIwMTQgYSBjYW5jZWwgaXMgbm90IGFuIGFuc3dlciwgYW5kIHRoZSBvZmZlciBoYXMgdG8gY29tZSBiYWNrLlxuICAgKi9cbiAgcmVhZG9ubHkgaXNBcHBsaWVkOiBib29sZWFuO1xufVxuXG4vKipcbiAqIFRoZSBBUEkgYSBwbHVnaW4gcHVibGlzaGVzIHdoZW4gaXQgaXMgd2lsbGluZyB0byByZWNlaXZlIHNldHRpbmdzIGFub3RoZXIgcGx1Z2luIHVzZWQgdG8gb3duLlxuICpcbiAqIEB0eXBlUGFyYW0gVE1pZ3JhdGFibGVTZXR0aW5ncyAtIFRoZSBzZXR0aW5ncyB0aGlzIHByb3ZpZGVyIGFjY2VwdHMuXG4gKlxuICogQHJlbWFya3NcbiAqIFRoZSBwcm92aWRlciBvd25zIHRoZSBzZXR0aW5ncywgc28gaXQgb3ducyB0aGUgZGlhbG9nOiBhIHByb3Bvc2luZyBwbHVnaW4gbmV2ZXIgd3JpdGVzIGludG8gYW5vdGhlclxuICogcGx1Z2luJ3MgYGRhdGEuanNvbmAuIEl0IHByb3Bvc2VzLCBhbmQgdGhlIHVzZXIgYXBwcm92ZXMsIGVkaXRzIG9yIGRlY2xpbmVzLlxuICovXG5leHBvcnQgaW50ZXJmYWNlIFNldHRpbmdzTWlncmF0aW9uQXBpPFRNaWdyYXRhYmxlU2V0dGluZ3MgZXh0ZW5kcyBvYmplY3Q+IHtcbiAgLyoqXG4gICAqIE9mZmVycyB0aGUgdXNlciBhIHNldCBvZiBzZXR0aW5ncyB2YWx1ZXMgYW5vdGhlciBwbHVnaW4gcHJvcG9zZXMsIGFuZCBhcHBsaWVzIHdoYXQgdGhleSBhcHByb3ZlLlxuICAgKlxuICAgKiBSZXNvbHZlcyBvbmx5IG9uY2UgdGhlIGRpYWxvZyBpcyBjbG9zZWQsIHNvIHRoZSBjYWxsZXIgbGVhcm5zIHdoZXRoZXIgdGhlIG1pZ3JhdGlvbiBhY3R1YWxseSBoYXBwZW5lZCBhbmRcbiAgICogY2FuIHJldGlyZSBcdTIwMTQgb3Igd2l0aGhvbGQgXHUyMDE0IGl0cyBvd24gcGVuZGluZyB2YWx1ZXMgb24gdGhhdCBhbnN3ZXIuXG4gICAqXG4gICAqIEBwYXJhbSBwYXJhbXMgLSBUaGUgcHJvcG9zYWwuXG4gICAqIEByZXR1cm5zIFdoYXQgdGhlIHVzZXIgYXBwcm92ZWQuXG4gICAqL1xuICBtaWdyYXRlU2V0dGluZ3MocGFyYW1zOiBNaWdyYXRlU2V0dGluZ3NQYXJhbXM8VE1pZ3JhdGFibGVTZXR0aW5ncz4pOiBQcm9taXNlPE1pZ3JhdGVTZXR0aW5nc1Jlc3VsdD47XG59XG4iXSwKICAibWFwcGluZ3MiOiAiOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7QUFBQTtBQUFBOyIsCiAgIm5hbWVzIjogW10KfQo=

package/dist/lib/cjs/obsidian/plugin/settings-migration-api.d.cts

@@ -0,0 +1,91 @@
+/// <reference path="../../library.d.cts" />
+/**
+ * @file
+ *
+ * The generic half of a settings HANDOVER contract: one plugin offers another the settings it used to own,
+ * and the plugin that owns them now decides what to do with the offer.
+ *
+ * The shape below is deliberately the *envelope* and nothing else. A handover has three parts, and only one
+ * of them is generic:
+ *
+ * - The **envelope** — a `migrateSettings` call, who is proposing, and whether the user applied it. Identical
+ *   for every pair of plugins, so it lives here.
+ * - The **payload** — which settings are being proposed. Entirely the pair's own business, so it stays a type
+ *   parameter and is never named here.
+ * - The **provider's identity** — its plugin id and display name. Also the pair's own business, and not
+ *   something this library has any standing to own.
+ *
+ * Why it is declared rather than imported. A provider is typically an Obsidian *plugin* repo, not an npm
+ * package, so a consumer has nothing to depend on and hand-writes its own copy of the contract. Five copies
+ * of one contract with no compiler link between them means drift is SILENT — every copy still compiles and
+ * the handover fails at runtime instead. Declaring the envelope here gives both ends one declaration to
+ * compile against; `watchPluginApi` still negotiates the version at runtime, because the two ends ship
+ * independently and always will.
+ *
+ * The provider publishes it:
+ *
+ * ```ts
+ * publishPluginApi<SettingsMigrationApi<MyMigratableSettings>>({
+ *   api: this.settingsMigrationApi,
+ *   apiVersion: '1.0.0',
+ *   contract: { migrateSettings: {} },
+ *   plugin: this
+ * });
+ * ```
+ *
+ * The consumer reaches it through {@link obsidian/components/settings-migration-component!SettingsMigrationComponent},
+ * which owns the whole offer-and-retire dance.
+ */
+/**
+ * Parameters for {@link SettingsMigrationApi.migrateSettings}.
+ *
+ * @typeParam TMigratableSettings - The settings the proposing plugin may hand over.
+ */
+export interface MigrateSettingsParams<TMigratableSettings extends object> {
+    /**
+     * The values the proposing plugin offers.
+     *
+     * Conventionally every member is optional, so a plugin proposes only what it actually held and a value the
+     * provider already owns is never overwritten by a default nobody chose. That convention belongs to the pair,
+     * though — this type imposes only the envelope.
+     */
+    readonly proposedSettings: TMigratableSettings;
+    /**
+     * The `manifest.id` of the plugin making the proposal, so the provider's dialog can say whose settings
+     * these are.
+     */
+    readonly sourcePluginId: string;
+}
+/**
+ * The outcome of {@link SettingsMigrationApi.migrateSettings}.
+ */
+export interface MigrateSettingsResult {
+    /**
+     * Whether the user approved the migration.
+     *
+     * `false` means they cancelled and nothing was written, so the proposing plugin must NOT record the
+     * migration as done — a cancel is not an answer, and the offer has to come back.
+     */
+    readonly isApplied: boolean;
+}
+/**
+ * The API a plugin publishes when it is willing to receive settings another plugin used to own.
+ *
+ * @typeParam TMigratableSettings - The settings this provider accepts.
+ *
+ * @remarks
+ * The provider owns the settings, so it owns the dialog: a proposing plugin never writes into another
+ * plugin's `data.json`. It proposes, and the user approves, edits or declines.
+ */
+export interface SettingsMigrationApi<TMigratableSettings extends object> {
+    /**
+     * Offers the user a set of settings values another plugin proposes, and applies what they approve.
+     *
+     * Resolves only once the dialog is closed, so the caller learns whether the migration actually happened and
+     * can retire — or withhold — its own pending values on that answer.
+     *
+     * @param params - The proposal.
+     * @returns What the user approved.
+     */
+    migrateSettings(params: MigrateSettingsParams<TMigratableSettings>): Promise<MigrateSettingsResult>;
+}

package/dist/lib/esm/__merged.d.mts

@@ -57,6 +57,7 @@ export { MenuEventRegistrarComponent } from './obsidian/components/menu-event-re
 export { around, hasPatchToken, MonkeyAroundComponent } from './obsidian/components/monkey-around-component.mjs';
 export { NotebookNavigatorMenuEventRegistrarComponent } from './obsidian/components/notebook-navigator-menu-event-registrar-component.mjs';
 export { PluginContextComponent } from './obsidian/components/plugin-context-component.mjs';
+export { PluginConflictSeverity, PluginGateComponent } from './obsidian/components/plugin-gate-component.mjs';
 export { PluginNoticeComponent, PluginNoticeMode } from './obsidian/components/plugin-notice-component.mjs';
 export { PluginSettingsComponentBase } from './obsidian/components/plugin-settings-component.mjs';
 export { PluginSettingsTabComponent } from './obsidian/components/plugin-settings-tab-component.mjs';
@@ -65,6 +66,7 @@ export { PointerPositionComponent } from './obsidian/components/pointer-position
 export { RegistryComponent } from './obsidian/components/registry-component.mjs';
 export { EmptyFolderBehavior, RenameDeleteHandlerComponent } from './obsidian/components/rename-delete-handler-component.mjs';
 export { NOT_EMPTY_DIRECTORY_ERROR_CODE, RmdirGuardComponent } from './obsidian/components/rmdir-guard-component.mjs';
+export { SettingsMigrationComponent } from './obsidian/components/settings-migration-component.mjs';
 export { SyntaxHighlightingComponent } from './obsidian/components/syntax-highlighting-component.mjs';
 export { getDomEventsHandlersConstructor } from './obsidian/constructors/get-dom-events-handlers-constructor.mjs';
 export { CssClass } from './obsidian/css-class.mjs';
@@ -86,7 +88,7 @@ export { FOLDER_NOTES_PLUGIN_ID, FolderNoteLocation, resolveFolderNote, resolveF
 export { isFrontmatterLinkCacheWithOffsets, toFrontmatterLinkCacheWithOffsets } from './obsidian/frontmatter-link-cache-with-offsets.mjs';
 export { parseFrontmatter, removeEmptyFrontmatterValues, setFrontmatter } from './obsidian/frontmatter.mjs';
 export { PluginHoverLinkSourceRegistrar } from './obsidian/hover-link-source-registrar.mjs';
-export { appendCodeBlock, applySpellcheckMode } from './obsidian/html-element.mjs';
+export { appendCodeBlock, applySpellcheckMode, asCodeBlock, createFragmentWithCodeBlocks } from './obsidian/html-element.mjs';
 export { DEFAULT_NS, initI18N, t } from './obsidian/i18n/i18n.mjs';
 export { en } from './obsidian/i18n/locales/en.mjs';
 export { DEFAULT_LANGUAGE, defaultTranslationsMap } from './obsidian/i18n/locales/translations-map.mjs';
@@ -121,6 +123,8 @@ export { ObsidianPluginRepoPaths } from './obsidian/plugin/obsidian-plugin-repo-
 export { PluginApiPayloadKind, PluginApiRevokedError, PluginApiUnavailabilityReason, PluginApiUnavailableError, PluginApiValidationError, publishPluginApi, watchPluginApi } from './obsidian/plugin/plugin-api.mjs';
 export { addPluginCssClasses, initDebugController, initPluginContext } from './obsidian/plugin/plugin-context.mjs';
 export { PluginEventSourceImpl } from './obsidian/plugin/plugin-event-source.mjs';
+export { getInstalledPluginState, getInstalledPluginVersion, installAndEnablePlugin, InstalledPluginState } from './obsidian/plugin/plugin-install-state.mjs';
+export { PLUGIN_LOADED_EVENT_NAME, PLUGIN_UNLOADED_EVENT_NAME, triggerPluginLifecycleEvent } from './obsidian/plugin/plugin-lifecycle-events.mjs';
 export { PluginSettingsTabBase, SAVE_TO_FILE_CONTEXT } from './obsidian/plugin/plugin-settings-tab.mjs';
 export { PluginBase, reloadPlugin, showErrorAndDisablePlugin } from './obsidian/plugin/plugin.mjs';
 export { editFieldsInPopover } from './obsidian/popovers/field-popover.mjs';