@mnaoumov/obsidian-lib 0.0.0 → 1.0.0

package/dist/lib/esm/components/rmdir-guard-component.d.mts

@@ -0,0 +1,76 @@
+/// <reference path="../library.d.mts" />
+/**
+ * @file
+ *
+ * Contains class {@link RmdirGuardComponent} that makes the `recursive` flag of
+ * {@link https://docs.obsidian.md/Reference/TypeScript+API/DataAdapter/rmdir | DataAdapter.rmdir} mean what it says.
+ */
+import type { App } from 'obsidian';
+import { MonkeyAroundComponent } from './monkey-around-component.mjs';
+/**
+ * The `code` carried by the error thrown when a non-recursive `rmdir` is refused because the folder has children.
+ *
+ * Matches the POSIX/Node error code a correct non-recursive directory removal produces, so a caller already
+ * branching on `error.code` keeps working. Check the `code`, never `instanceof` — every plugin bundles its own
+ * copy of this library, so the error may cross a copy boundary.
+ */
+export declare const NOT_EMPTY_DIRECTORY_ERROR_CODE = "ENOTEMPTY";
+/**
+ * Makes `app.vault.adapter.rmdir(path, false)` behave as its name promises: a non-recursive call on a folder
+ * that still has children throws instead of deleting them.
+ *
+ * @remarks
+ * Obsidian's adapters do not honor `recursive: false`, and they get it wrong in opposite directions:
+ *
+ * - `CapacitorAdapter` (mobile) does not accept the argument at all — it always removes recursively, so a
+ *   non-recursive call silently deletes the folder and everything under it. This is the data-loss footgun.
+ * - `FileSystemAdapter` (desktop) forwards it to `fs.promises.rm(path, { recursive })`, which throws
+ *   `ERR_FS_EISDIR` for *any* directory when `recursive` is `false` — so the non-recursive call never
+ *   succeeds, not even on an empty folder.
+ *
+ * While loaded, this component gives both platforms the same, correct behavior: a non-empty folder is
+ * refused with an {@link NOT_EMPTY_DIRECTORY_ERROR_CODE} error and nothing is deleted; an empty folder is
+ * removed. Emptiness is decided from the adapter (via {@link isEmptyFolder}), not from the vault index — the
+ * index omits dot-prefixed and otherwise hidden entries, so a folder holding only hidden files reads as empty
+ * there and the guard would wave through exactly the deletion it exists to prevent.
+ *
+ * A folder proven empty is removed by forwarding to the original method with `recursive: true`. That is not
+ * merely defensive: it is what makes the empty-folder case succeed on desktop, where the non-recursive call
+ * would otherwise throw.
+ *
+ * Calls that already pass `recursive: true`, and calls whose target is not a folder (a file, a missing path),
+ * are passed through untouched and keep their native behavior.
+ *
+ * Loading the guard more than once is safe, and it deliberately carries **no patch token**. Every plugin
+ * bundles its own copy of this library and they all patch the one shared adapter, so several guards do stack
+ * — but the operation is idempotent (prove empty, then delete), so stacking changes nothing: the outermost
+ * guard either throws or forwards with `recursive: true`, which every guard beneath passes straight through.
+ * They can also be unloaded in any order and the method stays guarded until the last one goes, because
+ * `monkey-around` neutralizes an unloaded wrapper in place rather than splicing it out. A token would only
+ * move the decision to the innermost guard — an equally arbitrary choice — while adding a path on which a
+ * guard declines to guard. For a data-loss guard that trade is not worth making. Contrast
+ * `RenameDeleteHandlerComponent`, which does need one: suppressing `runAsyncLinkUpdate` is not idempotent,
+ * so two of those would conflict.
+ *
+ * This component is deliberately **opt-in**: `app.vault.adapter` is shared by the whole app, so a library that
+ * installed this patch on its own would change `rmdir` semantics for every other plugin, including the ones
+ * that never asked for it. A plugin that deletes folders opts in for itself:
+ *
+ * @example
+ * ```ts
+ * this.addChild(new RmdirGuardComponent(this.app));
+ * ```
+ */
+export declare class RmdirGuardComponent extends MonkeyAroundComponent {
+    protected readonly app: App;
+    /**
+     * Creates a new instance of the {@link RmdirGuardComponent} class.
+     *
+     * @param app - The Obsidian app instance whose vault adapter to guard.
+     */
+    constructor(app: App);
+    /**
+     * Installs the `rmdir` guard. The patch is uninstalled when this component unloads.
+     */
+    onload(): void;
+}

package/dist/lib/esm/components/rmdir-guard-component.mjs

@@ -0,0 +1,100 @@
+/*
+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 ensureDisposeSymbols(symbolConstructor = Symbol) {
+  symbolConstructor.asyncDispose ??= symbolConstructor.for('Symbol.asyncDispose');
+  symbolConstructor.dispose ??= symbolConstructor.for('Symbol.dispose');
+}
+
+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 initEsm() {
+  ensureDisposeSymbols();
+  ensureBrowserProcess();
+})();
+})();
+
+import { isEmptyFolder } from "../vault.mjs";
+import { MonkeyAroundComponent } from "./monkey-around-component.mjs";
+const NOT_EMPTY_DIRECTORY_ERROR_CODE = "ENOTEMPTY";
+class RmdirGuardComponent extends MonkeyAroundComponent {
+  /**
+   * Creates a new instance of the {@link RmdirGuardComponent} class.
+   *
+   * @param app - The Obsidian app instance whose vault adapter to guard.
+   */
+  constructor(app) {
+    super();
+    this.app = app;
+  }
+  app;
+  /**
+   * Installs the `rmdir` guard. The patch is uninstalled when this component unloads.
+   */
+  onload() {
+    this.registerMethodPatch({
+      $object: this.app.vault.adapter,
+      methodName: "rmdir",
+      patchHandler: async ({
+        fallback,
+        originalArguments: [normalizedPath, recursive],
+        originalMethodBound
+      }) => {
+        if (recursive) {
+          await fallback();
+          return;
+        }
+        const stats = await this.app.vault.adapter.stat(normalizedPath);
+        if (stats?.type !== "folder") {
+          await fallback();
+          return;
+        }
+        if (!await isEmptyFolder(this.app, normalizedPath)) {
+          throw Object.assign(new Error(`Directory ${normalizedPath} is not empty`), {
+            code: NOT_EMPTY_DIRECTORY_ERROR_CODE,
+            path: normalizedPath
+          });
+        }
+        await originalMethodBound(normalizedPath, true);
+      }
+    });
+  }
+}
+export {
+  NOT_EMPTY_DIRECTORY_ERROR_CODE,
+  RmdirGuardComponent
+};
+//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFsiLi4vLi4vLi4vLi4vc3JjL2NvbXBvbmVudHMvcm1kaXItZ3VhcmQtY29tcG9uZW50LnRzIl0sCiAgInNvdXJjZXNDb250ZW50IjogWyIvKipcbiAqIEBmaWxlXG4gKlxuICogQ29udGFpbnMgY2xhc3Mge0BsaW5rIFJtZGlyR3VhcmRDb21wb25lbnR9IHRoYXQgbWFrZXMgdGhlIGByZWN1cnNpdmVgIGZsYWcgb2ZcbiAqIHtAbGluayBodHRwczovL2RvY3Mub2JzaWRpYW4ubWQvUmVmZXJlbmNlL1R5cGVTY3JpcHQrQVBJL0RhdGFBZGFwdGVyL3JtZGlyIHwgRGF0YUFkYXB0ZXIucm1kaXJ9IG1lYW4gd2hhdCBpdCBzYXlzLlxuICovXG5cbmltcG9ydCB0eXBlIHsgQXBwIH0gZnJvbSAnb2JzaWRpYW4nO1xuXG5pbXBvcnQgeyBpc0VtcHR5Rm9sZGVyIH0gZnJvbSAnLi4vdmF1bHQudHMnO1xuaW1wb3J0IHsgTW9ua2V5QXJvdW5kQ29tcG9uZW50IH0gZnJvbSAnLi9tb25rZXktYXJvdW5kLWNvbXBvbmVudC50cyc7XG5cbi8qKlxuICogVGhlIGBjb2RlYCBjYXJyaWVkIGJ5IHRoZSBlcnJvciB0aHJvd24gd2hlbiBhIG5vbi1yZWN1cnNpdmUgYHJtZGlyYCBpcyByZWZ1c2VkIGJlY2F1c2UgdGhlIGZvbGRlciBoYXMgY2hpbGRyZW4uXG4gKlxuICogTWF0Y2hlcyB0aGUgUE9TSVgvTm9kZSBlcnJvciBjb2RlIGEgY29ycmVjdCBub24tcmVjdXJzaXZlIGRpcmVjdG9yeSByZW1vdmFsIHByb2R1Y2VzLCBzbyBhIGNhbGxlciBhbHJlYWR5XG4gKiBicmFuY2hpbmcgb24gYGVycm9yLmNvZGVgIGtlZXBzIHdvcmtpbmcuIENoZWNrIHRoZSBgY29kZWAsIG5ldmVyIGBpbnN0YW5jZW9mYCBcdTIwMTQgZXZlcnkgcGx1Z2luIGJ1bmRsZXMgaXRzIG93blxuICogY29weSBvZiB0aGlzIGxpYnJhcnksIHNvIHRoZSBlcnJvciBtYXkgY3Jvc3MgYSBjb3B5IGJvdW5kYXJ5LlxuICovXG5leHBvcnQgY29uc3QgTk9UX0VNUFRZX0RJUkVDVE9SWV9FUlJPUl9DT0RFID0gJ0VOT1RFTVBUWSc7XG5cbi8qKlxuICogTWFrZXMgYGFwcC52YXVsdC5hZGFwdGVyLnJtZGlyKHBhdGgsIGZhbHNlKWAgYmVoYXZlIGFzIGl0cyBuYW1lIHByb21pc2VzOiBhIG5vbi1yZWN1cnNpdmUgY2FsbCBvbiBhIGZvbGRlclxuICogdGhhdCBzdGlsbCBoYXMgY2hpbGRyZW4gdGhyb3dzIGluc3RlYWQgb2YgZGVsZXRpbmcgdGhlbS5cbiAqXG4gKiBAcmVtYXJrc1xuICogT2JzaWRpYW4ncyBhZGFwdGVycyBkbyBub3QgaG9ub3IgYHJlY3Vyc2l2ZTogZmFsc2VgLCBhbmQgdGhleSBnZXQgaXQgd3JvbmcgaW4gb3Bwb3NpdGUgZGlyZWN0aW9uczpcbiAqXG4gKiAtIGBDYXBhY2l0b3JBZGFwdGVyYCAobW9iaWxlKSBkb2VzIG5vdCBhY2NlcHQgdGhlIGFyZ3VtZW50IGF0IGFsbCBcdTIwMTQgaXQgYWx3YXlzIHJlbW92ZXMgcmVjdXJzaXZlbHksIHNvIGFcbiAqICAgbm9uLXJlY3Vyc2l2ZSBjYWxsIHNpbGVudGx5IGRlbGV0ZXMgdGhlIGZvbGRlciBhbmQgZXZlcnl0aGluZyB1bmRlciBpdC4gVGhpcyBpcyB0aGUgZGF0YS1sb3NzIGZvb3RndW4uXG4gKiAtIGBGaWxlU3lzdGVtQWRhcHRlcmAgKGRlc2t0b3ApIGZvcndhcmRzIGl0IHRvIGBmcy5wcm9taXNlcy5ybShwYXRoLCB7IHJlY3Vyc2l2ZSB9KWAsIHdoaWNoIHRocm93c1xuICogICBgRVJSX0ZTX0VJU0RJUmAgZm9yICphbnkqIGRpcmVjdG9yeSB3aGVuIGByZWN1cnNpdmVgIGlzIGBmYWxzZWAgXHUyMDE0IHNvIHRoZSBub24tcmVjdXJzaXZlIGNhbGwgbmV2ZXJcbiAqICAgc3VjY2VlZHMsIG5vdCBldmVuIG9uIGFuIGVtcHR5IGZvbGRlci5cbiAqXG4gKiBXaGlsZSBsb2FkZWQsIHRoaXMgY29tcG9uZW50IGdpdmVzIGJvdGggcGxhdGZvcm1zIHRoZSBzYW1lLCBjb3JyZWN0IGJlaGF2aW9yOiBhIG5vbi1lbXB0eSBmb2xkZXIgaXNcbiAqIHJlZnVzZWQgd2l0aCBhbiB7QGxpbmsgTk9UX0VNUFRZX0RJUkVDVE9SWV9FUlJPUl9DT0RFfSBlcnJvciBhbmQgbm90aGluZyBpcyBkZWxldGVkOyBhbiBlbXB0eSBmb2xkZXIgaXNcbiAqIHJlbW92ZWQuIEVtcHRpbmVzcyBpcyBkZWNpZGVkIGZyb20gdGhlIGFkYXB0ZXIgKHZpYSB7QGxpbmsgaXNFbXB0eUZvbGRlcn0pLCBub3QgZnJvbSB0aGUgdmF1bHQgaW5kZXggXHUyMDE0IHRoZVxuICogaW5kZXggb21pdHMgZG90LXByZWZpeGVkIGFuZCBvdGhlcndpc2UgaGlkZGVuIGVudHJpZXMsIHNvIGEgZm9sZGVyIGhvbGRpbmcgb25seSBoaWRkZW4gZmlsZXMgcmVhZHMgYXMgZW1wdHlcbiAqIHRoZXJlIGFuZCB0aGUgZ3VhcmQgd291bGQgd2F2ZSB0aHJvdWdoIGV4YWN0bHkgdGhlIGRlbGV0aW9uIGl0IGV4aXN0cyB0byBwcmV2ZW50LlxuICpcbiAqIEEgZm9sZGVyIHByb3ZlbiBlbXB0eSBpcyByZW1vdmVkIGJ5IGZvcndhcmRpbmcgdG8gdGhlIG9yaWdpbmFsIG1ldGhvZCB3aXRoIGByZWN1cnNpdmU6IHRydWVgLiBUaGF0IGlzIG5vdFxuICogbWVyZWx5IGRlZmVuc2l2ZTogaXQgaXMgd2hhdCBtYWtlcyB0aGUgZW1wdHktZm9sZGVyIGNhc2Ugc3VjY2VlZCBvbiBkZXNrdG9wLCB3aGVyZSB0aGUgbm9uLXJlY3Vyc2l2ZSBjYWxsXG4gKiB3b3VsZCBvdGhlcndpc2UgdGhyb3cuXG4gKlxuICogQ2FsbHMgdGhhdCBhbHJlYWR5IHBhc3MgYHJlY3Vyc2l2ZTogdHJ1ZWAsIGFuZCBjYWxscyB3aG9zZSB0YXJnZXQgaXMgbm90IGEgZm9sZGVyIChhIGZpbGUsIGEgbWlzc2luZyBwYXRoKSxcbiAqIGFyZSBwYXNzZWQgdGhyb3VnaCB1bnRvdWNoZWQgYW5kIGtlZXAgdGhlaXIgbmF0aXZlIGJlaGF2aW9yLlxuICpcbiAqIExvYWRpbmcgdGhlIGd1YXJkIG1vcmUgdGhhbiBvbmNlIGlzIHNhZmUsIGFuZCBpdCBkZWxpYmVyYXRlbHkgY2FycmllcyAqKm5vIHBhdGNoIHRva2VuKiouIEV2ZXJ5IHBsdWdpblxuICogYnVuZGxlcyBpdHMgb3duIGNvcHkgb2YgdGhpcyBsaWJyYXJ5IGFuZCB0aGV5IGFsbCBwYXRjaCB0aGUgb25lIHNoYXJlZCBhZGFwdGVyLCBzbyBzZXZlcmFsIGd1YXJkcyBkbyBzdGFja1xuICogXHUyMDE0IGJ1dCB0aGUgb3BlcmF0aW9uIGlzIGlkZW1wb3RlbnQgKHByb3ZlIGVtcHR5LCB0aGVuIGRlbGV0ZSksIHNvIHN0YWNraW5nIGNoYW5nZXMgbm90aGluZzogdGhlIG91dGVybW9zdFxuICogZ3VhcmQgZWl0aGVyIHRocm93cyBvciBmb3J3YXJkcyB3aXRoIGByZWN1cnNpdmU6IHRydWVgLCB3aGljaCBldmVyeSBndWFyZCBiZW5lYXRoIHBhc3NlcyBzdHJhaWdodCB0aHJvdWdoLlxuICogVGhleSBjYW4gYWxzbyBiZSB1bmxvYWRlZCBpbiBhbnkgb3JkZXIgYW5kIHRoZSBtZXRob2Qgc3RheXMgZ3VhcmRlZCB1bnRpbCB0aGUgbGFzdCBvbmUgZ29lcywgYmVjYXVzZVxuICogYG1vbmtleS1hcm91bmRgIG5ldXRyYWxpemVzIGFuIHVubG9hZGVkIHdyYXBwZXIgaW4gcGxhY2UgcmF0aGVyIHRoYW4gc3BsaWNpbmcgaXQgb3V0LiBBIHRva2VuIHdvdWxkIG9ubHlcbiAqIG1vdmUgdGhlIGRlY2lzaW9uIHRvIHRoZSBpbm5lcm1vc3QgZ3VhcmQgXHUyMDE0IGFuIGVxdWFsbHkgYXJiaXRyYXJ5IGNob2ljZSBcdTIwMTQgd2hpbGUgYWRkaW5nIGEgcGF0aCBvbiB3aGljaCBhXG4gKiBndWFyZCBkZWNsaW5lcyB0byBndWFyZC4gRm9yIGEgZGF0YS1sb3NzIGd1YXJkIHRoYXQgdHJhZGUgaXMgbm90IHdvcnRoIG1ha2luZy4gQ29udHJhc3RcbiAqIGBSZW5hbWVEZWxldGVIYW5kbGVyQ29tcG9uZW50YCwgd2hpY2ggZG9lcyBuZWVkIG9uZTogc3VwcHJlc3NpbmcgYHJ1bkFzeW5jTGlua1VwZGF0ZWAgaXMgbm90IGlkZW1wb3RlbnQsXG4gKiBzbyB0d28gb2YgdGhvc2Ugd291bGQgY29uZmxpY3QuXG4gKlxuICogVGhpcyBjb21wb25lbnQgaXMgZGVsaWJlcmF0ZWx5ICoqb3B0LWluKio6IGBhcHAudmF1bHQuYWRhcHRlcmAgaXMgc2hhcmVkIGJ5IHRoZSB3aG9sZSBhcHAsIHNvIGEgbGlicmFyeSB0aGF0XG4gKiBpbnN0YWxsZWQgdGhpcyBwYXRjaCBvbiBpdHMgb3duIHdvdWxkIGNoYW5nZSBgcm1kaXJgIHNlbWFudGljcyBmb3IgZXZlcnkgb3RoZXIgcGx1Z2luLCBpbmNsdWRpbmcgdGhlIG9uZXNcbiAqIHRoYXQgbmV2ZXIgYXNrZWQgZm9yIGl0LiBBIHBsdWdpbiB0aGF0IGRlbGV0ZXMgZm9sZGVycyBvcHRzIGluIGZvciBpdHNlbGY6XG4gKlxuICogQGV4YW1wbGVcbiAqIGBgYHRzXG4gKiB0aGlzLmFkZENoaWxkKG5ldyBSbWRpckd1YXJkQ29tcG9uZW50KHRoaXMuYXBwKSk7XG4gKiBgYGBcbiAqL1xuZXhwb3J0IGNsYXNzIFJtZGlyR3VhcmRDb21wb25lbnQgZXh0ZW5kcyBNb25rZXlBcm91bmRDb21wb25lbnQge1xuICAvKipcbiAgICogQ3JlYXRlcyBhIG5ldyBpbnN0YW5jZSBvZiB0aGUge0BsaW5rIFJtZGlyR3VhcmRDb21wb25lbnR9IGNsYXNzLlxuICAgKlxuICAgKiBAcGFyYW0gYXBwIC0gVGhlIE9ic2lkaWFuIGFwcCBpbnN0YW5jZSB3aG9zZSB2YXVsdCBhZGFwdGVyIHRvIGd1YXJkLlxuICAgKi9cbiAgcHVibGljIGNvbnN0cnVjdG9yKHByb3RlY3RlZCByZWFkb25seSBhcHA6IEFwcCkge1xuICAgIHN1cGVyKCk7XG4gIH1cblxuICAvKipcbiAgICogSW5zdGFsbHMgdGhlIGBybWRpcmAgZ3VhcmQuIFRoZSBwYXRjaCBpcyB1bmluc3RhbGxlZCB3aGVuIHRoaXMgY29tcG9uZW50IHVubG9hZHMuXG4gICAqL1xuICBwdWJsaWMgb3ZlcnJpZGUgb25sb2FkKCk6IHZvaWQge1xuICAgIHRoaXMucmVnaXN0ZXJNZXRob2RQYXRjaCh7XG4gICAgICAkb2JqZWN0OiB0aGlzLmFwcC52YXVsdC5hZGFwdGVyLFxuICAgICAgbWV0aG9kTmFtZTogJ3JtZGlyJyxcbiAgICAgIHBhdGNoSGFuZGxlcjogYXN5bmMgKHtcbiAgICAgICAgZmFsbGJhY2ssXG4gICAgICAgIG9yaWdpbmFsQXJndW1lbnRzOiBbbm9ybWFsaXplZFBhdGgsIHJlY3Vyc2l2ZV0sXG4gICAgICAgIG9yaWdpbmFsTWV0aG9kQm91bmRcbiAgICAgIH0pID0+IHtcbiAgICAgICAgaWYgKHJlY3Vyc2l2ZSkge1xuICAgICAgICAgIGF3YWl0IGZhbGxiYWNrKCk7XG4gICAgICAgICAgcmV0dXJuO1xuICAgICAgICB9XG5cbiAgICAgICAgY29uc3Qgc3RhdHMgPSBhd2FpdCB0aGlzLmFwcC52YXVsdC5hZGFwdGVyLnN0YXQobm9ybWFsaXplZFBhdGgpO1xuICAgICAgICBpZiAoc3RhdHM/LnR5cGUgIT09ICdmb2xkZXInKSB7XG4gICAgICAgICAgYXdhaXQgZmFsbGJhY2soKTtcbiAgICAgICAgICByZXR1cm47XG4gICAgICAgIH1cblxuICAgICAgICBpZiAoIWF3YWl0IGlzRW1wdHlGb2xkZXIodGhpcy5hcHAsIG5vcm1hbGl6ZWRQYXRoKSkge1xuICAgICAgICAgIHRocm93IE9iamVjdC5hc3NpZ24obmV3IEVycm9yKGBEaXJlY3RvcnkgJHtub3JtYWxpemVkUGF0aH0gaXMgbm90IGVtcHR5YCksIHtcbiAgICAgICAgICAgIGNvZGU6IE5PVF9FTVBUWV9ESVJFQ1RPUllfRVJST1JfQ09ERSxcbiAgICAgICAgICAgIHBhdGg6IG5vcm1hbGl6ZWRQYXRoXG4gICAgICAgICAgfSk7XG4gICAgICAgIH1cblxuICAgICAgICAvLyBUaGUgZm9sZGVyIGlzIHByb3ZlbiBlbXB0eSwgc28gYSByZWN1cnNpdmUgcmVtb3ZhbCBpcyBlcXVpdmFsZW50IC0tIGFuZCwgdW5saWtlIHRoZSBub24tcmVjdXJzaXZlXG4gICAgICAgIC8vIG9uZSwgaXQgYWN0dWFsbHkgd29ya3Mgb24gdGhlIGRlc2t0b3AgYWRhcHRlci5cbiAgICAgICAgYXdhaXQgb3JpZ2luYWxNZXRob2RCb3VuZChub3JtYWxpemVkUGF0aCwgdHJ1ZSk7XG4gICAgICB9XG4gICAgfSk7XG4gIH1cbn1cbiJdLAogICJtYXBwaW5ncyI6ICI7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7QUFTQSxTQUFTLHFCQUFxQjtBQUM5QixTQUFTLDZCQUE2QjtBQVMvQixNQUFNLGlDQUFpQztBQWdEdkMsTUFBTSw0QkFBNEIsc0JBQXNCO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBLEVBTXRELFlBQStCLEtBQVU7QUFDOUMsVUFBTTtBQUQ4QjtBQUFBLEVBRXRDO0FBQUEsRUFGc0M7QUFBQTtBQUFBO0FBQUE7QUFBQSxFQU90QixTQUFlO0FBQzdCLFNBQUssb0JBQW9CO0FBQUEsTUFDdkIsU0FBUyxLQUFLLElBQUksTUFBTTtBQUFBLE1BQ3hCLFlBQVk7QUFBQSxNQUNaLGNBQWMsT0FBTztBQUFBLFFBQ25CO0FBQUEsUUFDQSxtQkFBbUIsQ0FBQyxnQkFBZ0IsU0FBUztBQUFBLFFBQzdDO0FBQUEsTUFDRixNQUFNO0FBQ0osWUFBSSxXQUFXO0FBQ2IsZ0JBQU0sU0FBUztBQUNmO0FBQUEsUUFDRjtBQUVBLGNBQU0sUUFBUSxNQUFNLEtBQUssSUFBSSxNQUFNLFFBQVEsS0FBSyxjQUFjO0FBQzlELFlBQUksT0FBTyxTQUFTLFVBQVU7QUFDNUIsZ0JBQU0sU0FBUztBQUNmO0FBQUEsUUFDRjtBQUVBLFlBQUksQ0FBQyxNQUFNLGNBQWMsS0FBSyxLQUFLLGNBQWMsR0FBRztBQUNsRCxnQkFBTSxPQUFPLE9BQU8sSUFBSSxNQUFNLGFBQWEsY0FBYyxlQUFlLEdBQUc7QUFBQSxZQUN6RSxNQUFNO0FBQUEsWUFDTixNQUFNO0FBQUEsVUFDUixDQUFDO0FBQUEsUUFDSDtBQUlBLGNBQU0sb0JBQW9CLGdCQUFnQixJQUFJO0FBQUEsTUFDaEQ7QUFBQSxJQUNGLENBQUM7QUFBQSxFQUNIO0FBQ0Y7IiwKICAibmFtZXMiOiBbXQp9Cg==

package/dist/lib/esm/components/settings-migration-component.d.mts

@@ -0,0 +1,120 @@
+/// <reference path="../library.d.mts" />
+/**
+ * @file
+ *
+ * Component that offers settings this plugin used to own to the plugin that owns them now, once, through
+ * that plugin's public API.
+ *
+ * This is the other half of {@link components/plugin-suggestion-component!PluginSuggestionComponent}.
+ * The suggestion asks the user to install the plugin that took a feature over; this carries the settings they
+ * had configured for it across, so taking the suggestion does not mean re-entering everything by hand.
+ *
+ * A proposing plugin never writes into another plugin's `data.json`. It PROPOSES: the other plugin owns the
+ * settings, so it owns the dialog, and the user approves, edits or declines. Only an applied migration retires
+ * the pending values.
+ *
+ * The offer is made whenever it CAN succeed, which needs two independent things to have happened — the
+ * provider's API being available, and this plugin's own settings having arrived from disk. Either can land
+ * first, so both edges are wired and each re-reads the current state rather than assuming the other has
+ * already happened.
+ */
+import type { App } from 'obsidian';
+import type { Promisable } from 'type-fest';
+import type { PluginApiContract } from '../plugin/plugin-api.mjs';
+import type { PluginSettingsComponentBase } from './plugin-settings-component.mjs';
+import { ComponentEx } from './component-ex.mjs';
+/**
+ * Parameters for the {@link SettingsMigrationComponent} constructor.
+ *
+ * @typeParam TMigratableSettings - The settings this plugin may hand over.
+ */
+export interface SettingsMigrationComponentConstructorParams<TMigratableSettings extends object> {
+    /**
+     * The semver range of contract versions this plugin compiled against, e.g. `'^1'`.
+     *
+     * @remarks
+     * Evaluated by `compare-versions`, which does NOT accept a bare `*`. Spell "any version" as `'>=0.0.0'`.
+     */
+    readonly apiVersionRange: string;
+    /**
+     * The Obsidian app instance.
+     */
+    readonly app: App;
+    /**
+     * The contract this plugin expects of the provider, which wins over the provider's own when supplied.
+     *
+     * Worth supplying, and worth keeping NARROW. A migration usually needs one method that has existed since the
+     * provider's first contract version, while the same plugin may read other parts of that API through a much
+     * newer one. Declaring the wider expectation here would refuse to offer the migration to a user on an older
+     * provider — which is precisely the user who still has settings to migrate.
+     */
+    readonly contract?: PluginApiContract;
+    /**
+     * Reads the values currently waiting to be handed over.
+     *
+     * Called afresh on every edge rather than once, so an implementation simply reads its plugin's settings.
+     * Return `null` when there is nothing pending — after a migration has been applied, or on a vault that never
+     * had these settings configured.
+     *
+     * @returns The values to propose, or `null` when there is nothing to offer.
+     */
+    readonly getProposedSettings: () => null | TMigratableSettings;
+    /**
+     * The settings component of the plugin making the proposal.
+     *
+     * Taken as a whole component rather than as a bare "ready" flag so the host cannot forget to wire the wait:
+     * whatever {@link getProposedSettings} reads is meaningless until this component has read `data.json`.
+     */
+    readonly pluginSettingsComponent: PluginSettingsComponentBase<object>;
+    /**
+     * The `manifest.id` of the plugin that owns these settings now, as listed in Obsidian's community plugin
+     * registry.
+     */
+    readonly providerPluginId: string;
+    /**
+     * Records that the pending values have been handed over, so the offer is not made again.
+     *
+     * Called ONLY when the user actually applied the migration.
+     *
+     * @returns A {@link Promise} that resolves once the retirement is persisted.
+     *
+     * @remarks
+     * An implementation must PERSIST the retirement — `pluginSettingsComponent.editAndSave(…)`, not
+     * `setProperty(…)`. The latter only edits the in-memory state, so the retirement is forgotten on the next
+     * reload and the migration is offered again forever.
+     */
+    readonly retireProposedSettings: () => Promisable<void>;
+    /**
+     * The `manifest.id` of the plugin making the proposal, so the provider's dialog can say whose settings these
+     * are.
+     */
+    readonly sourcePluginId: string;
+}
+/**
+ * Offers settings this plugin used to own to the plugin that owns them now.
+ *
+ * @typeParam TMigratableSettings - The settings this plugin may hand over.
+ */
+export declare class SettingsMigrationComponent<TMigratableSettings extends object> extends ComponentEx {
+    private readonly apiVersionRange;
+    private readonly app;
+    private readonly contract;
+    private readonly getProposedSettings;
+    private isProposing;
+    private readonly pluginSettingsComponent;
+    private readonly providerPluginId;
+    private readonly retireProposedSettings;
+    private readonly sourcePluginId;
+    /**
+     * Creates an instance of {@link SettingsMigrationComponent}.
+     *
+     * @param params - The constructor parameters.
+     */
+    constructor(params: SettingsMigrationComponentConstructorParams<TMigratableSettings>);
+    /**
+     * Loads the component, wiring both edges that can make an offer possible.
+     */
+    onload(): void;
+    private handleChange;
+    private propose;
+}

package/dist/lib/esm/components/settings-migration-component.mjs

@@ -0,0 +1,133 @@
+/*
+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 ensureDisposeSymbols(symbolConstructor = Symbol) {
+  symbolConstructor.asyncDispose ??= symbolConstructor.for('Symbol.asyncDispose');
+  symbolConstructor.dispose ??= symbolConstructor.for('Symbol.dispose');
+}
+
+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 initEsm() {
+  ensureDisposeSymbols();
+  ensureBrowserProcess();
+})();
+})();
+
+import { invokeAsyncSafely } from "@mnaoumov/typescript-lib/async";
+import { normalizeOptionalProperties } from "@mnaoumov/typescript-lib/object-utils";
+import { watchPluginApi } from "../plugin/plugin-api.mjs";
+import { registerAsyncEvent } from "./async-events-component.mjs";
+import { ComponentEx } from "./component-ex.mjs";
+class SettingsMigrationComponent extends ComponentEx {
+  apiVersionRange;
+  app;
+  contract;
+  getProposedSettings;
+  isProposing = false;
+  pluginSettingsComponent;
+  providerPluginId;
+  retireProposedSettings;
+  sourcePluginId;
+  /**
+   * Creates an instance of {@link SettingsMigrationComponent}.
+   *
+   * @param params - The constructor parameters.
+   */
+  constructor(params) {
+    super();
+    this.apiVersionRange = params.apiVersionRange;
+    this.app = params.app;
+    this.contract = params.contract;
+    this.getProposedSettings = params.getProposedSettings;
+    this.pluginSettingsComponent = params.pluginSettingsComponent;
+    this.providerPluginId = params.providerPluginId;
+    this.retireProposedSettings = params.retireProposedSettings;
+    this.sourcePluginId = params.sourcePluginId;
+  }
+  /**
+   * Loads the component, wiring both edges that can make an offer possible.
+   */
+  onload() {
+    const ref = watchPluginApi(normalizeOptionalProperties({
+      apiVersionRange: this.apiVersionRange,
+      app: this.app,
+      component: this,
+      contract: this.contract,
+      pluginId: this.providerPluginId
+    }));
+    registerAsyncEvent(
+      this,
+      ref.on("change", () => {
+        this.handleChange(ref);
+      })
+    );
+    registerAsyncEvent(
+      this,
+      this.pluginSettingsComponent.on("loadSettings", () => {
+        this.handleChange(ref);
+      })
+    );
+    this.handleChange(ref);
+  }
+  handleChange(ref) {
+    invokeAsyncSafely(async () => {
+      await this.propose(ref.value);
+    });
+  }
+  async propose(api) {
+    const proposedSettings = this.getProposedSettings();
+    if (!api || this.isProposing || proposedSettings === null) {
+      return;
+    }
+    this.isProposing = true;
+    try {
+      const result = await api.migrateSettings({
+        proposedSettings,
+        sourcePluginId: this.sourcePluginId
+      });
+      if (result.isApplied) {
+        await this.retireProposedSettings();
+      }
+    } finally {
+      this.isProposing = false;
+    }
+  }
+}
+export {
+  SettingsMigrationComponent
+};
+//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFsiLi4vLi4vLi4vLi4vc3JjL2NvbXBvbmVudHMvc2V0dGluZ3MtbWlncmF0aW9uLWNvbXBvbmVudC50cyJdLAogICJzb3VyY2VzQ29udGVudCI6IFsiLyoqXG4gKiBAZmlsZVxuICpcbiAqIENvbXBvbmVudCB0aGF0IG9mZmVycyBzZXR0aW5ncyB0aGlzIHBsdWdpbiB1c2VkIHRvIG93biB0byB0aGUgcGx1Z2luIHRoYXQgb3ducyB0aGVtIG5vdywgb25jZSwgdGhyb3VnaFxuICogdGhhdCBwbHVnaW4ncyBwdWJsaWMgQVBJLlxuICpcbiAqIFRoaXMgaXMgdGhlIG90aGVyIGhhbGYgb2Yge0BsaW5rIGNvbXBvbmVudHMvcGx1Z2luLXN1Z2dlc3Rpb24tY29tcG9uZW50IVBsdWdpblN1Z2dlc3Rpb25Db21wb25lbnR9LlxuICogVGhlIHN1Z2dlc3Rpb24gYXNrcyB0aGUgdXNlciB0byBpbnN0YWxsIHRoZSBwbHVnaW4gdGhhdCB0b29rIGEgZmVhdHVyZSBvdmVyOyB0aGlzIGNhcnJpZXMgdGhlIHNldHRpbmdzIHRoZXlcbiAqIGhhZCBjb25maWd1cmVkIGZvciBpdCBhY3Jvc3MsIHNvIHRha2luZyB0aGUgc3VnZ2VzdGlvbiBkb2VzIG5vdCBtZWFuIHJlLWVudGVyaW5nIGV2ZXJ5dGhpbmcgYnkgaGFuZC5cbiAqXG4gKiBBIHByb3Bvc2luZyBwbHVnaW4gbmV2ZXIgd3JpdGVzIGludG8gYW5vdGhlciBwbHVnaW4ncyBgZGF0YS5qc29uYC4gSXQgUFJPUE9TRVM6IHRoZSBvdGhlciBwbHVnaW4gb3ducyB0aGVcbiAqIHNldHRpbmdzLCBzbyBpdCBvd25zIHRoZSBkaWFsb2csIGFuZCB0aGUgdXNlciBhcHByb3ZlcywgZWRpdHMgb3IgZGVjbGluZXMuIE9ubHkgYW4gYXBwbGllZCBtaWdyYXRpb24gcmV0aXJlc1xuICogdGhlIHBlbmRpbmcgdmFsdWVzLlxuICpcbiAqIFRoZSBvZmZlciBpcyBtYWRlIHdoZW5ldmVyIGl0IENBTiBzdWNjZWVkLCB3aGljaCBuZWVkcyB0d28gaW5kZXBlbmRlbnQgdGhpbmdzIHRvIGhhdmUgaGFwcGVuZWQgXHUyMDE0IHRoZVxuICogcHJvdmlkZXIncyBBUEkgYmVpbmcgYXZhaWxhYmxlLCBhbmQgdGhpcyBwbHVnaW4ncyBvd24gc2V0dGluZ3MgaGF2aW5nIGFycml2ZWQgZnJvbSBkaXNrLiBFaXRoZXIgY2FuIGxhbmRcbiAqIGZpcnN0LCBzbyBib3RoIGVkZ2VzIGFyZSB3aXJlZCBhbmQgZWFjaCByZS1yZWFkcyB0aGUgY3VycmVudCBzdGF0ZSByYXRoZXIgdGhhbiBhc3N1bWluZyB0aGUgb3RoZXIgaGFzXG4gKiBhbHJlYWR5IGhhcHBlbmVkLlxuICovXG5cbmltcG9ydCB0eXBlIHsgQXBwIH0gZnJvbSAnb2JzaWRpYW4nO1xuaW1wb3J0IHR5cGUgeyBQcm9taXNhYmxlIH0gZnJvbSAndHlwZS1mZXN0JztcblxuaW1wb3J0IHsgaW52b2tlQXN5bmNTYWZlbHkgfSBmcm9tICdAbW5hb3Vtb3YvdHlwZXNjcmlwdC1saWIvYXN5bmMnO1xuaW1wb3J0IHsgbm9ybWFsaXplT3B0aW9uYWxQcm9wZXJ0aWVzIH0gZnJvbSAnQG1uYW91bW92L3R5cGVzY3JpcHQtbGliL29iamVjdC11dGlscyc7XG5cbmltcG9ydCB0eXBlIHtcbiAgUGx1Z2luQXBpQ29udHJhY3QsXG4gIFBsdWdpbkFwaVJlZixcbiAgV2F0Y2hQbHVnaW5BcGlQYXJhbXNcbn0gZnJvbSAnLi4vcGx1Z2luL3BsdWdpbi1hcGkudHMnO1xuaW1wb3J0IHR5cGUgeyBTZXR0aW5nc01pZ3JhdGlvbkFwaSB9IGZyb20gJy4uL3BsdWdpbi9zZXR0aW5ncy1taWdyYXRpb24tYXBpLnRzJztcbmltcG9ydCB0eXBlIHsgUGx1Z2luU2V0dGluZ3NDb21wb25lbnRCYXNlIH0gZnJvbSAnLi9wbHVnaW4tc2V0dGluZ3MtY29tcG9uZW50LnRzJztcblxuaW1wb3J0IHsgd2F0Y2hQbHVnaW5BcGkgfSBmcm9tICcuLi9wbHVnaW4vcGx1Z2luLWFwaS50cyc7XG5pbXBvcnQgeyByZWdpc3RlckFzeW5jRXZlbnQgfSBmcm9tICcuL2FzeW5jLWV2ZW50cy1jb21wb25lbnQudHMnO1xuaW1wb3J0IHsgQ29tcG9uZW50RXggfSBmcm9tICcuL2NvbXBvbmVudC1leC50cyc7XG5cbi8qKlxuICogUGFyYW1ldGVycyBmb3IgdGhlIHtAbGluayBTZXR0aW5nc01pZ3JhdGlvbkNvbXBvbmVudH0gY29uc3RydWN0b3IuXG4gKlxuICogQHR5cGVQYXJhbSBUTWlncmF0YWJsZVNldHRpbmdzIC0gVGhlIHNldHRpbmdzIHRoaXMgcGx1Z2luIG1heSBoYW5kIG92ZXIuXG4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgU2V0dGluZ3NNaWdyYXRpb25Db21wb25lbnRDb25zdHJ1Y3RvclBhcmFtczxUTWlncmF0YWJsZVNldHRpbmdzIGV4dGVuZHMgb2JqZWN0PiB7XG4gIC8qKlxuICAgKiBUaGUgc2VtdmVyIHJhbmdlIG9mIGNvbnRyYWN0IHZlcnNpb25zIHRoaXMgcGx1Z2luIGNvbXBpbGVkIGFnYWluc3QsIGUuZy4gYCdeMSdgLlxuICAgKlxuICAgKiBAcmVtYXJrc1xuICAgKiBFdmFsdWF0ZWQgYnkgYGNvbXBhcmUtdmVyc2lvbnNgLCB3aGljaCBkb2VzIE5PVCBhY2NlcHQgYSBiYXJlIGAqYC4gU3BlbGwgXCJhbnkgdmVyc2lvblwiIGFzIGAnPj0wLjAuMCdgLlxuICAgKi9cbiAgcmVhZG9ubHkgYXBpVmVyc2lvblJhbmdlOiBzdHJpbmc7XG5cbiAgLyoqXG4gICAqIFRoZSBPYnNpZGlhbiBhcHAgaW5zdGFuY2UuXG4gICAqL1xuICByZWFkb25seSBhcHA6IEFwcDtcblxuICAvKipcbiAgICogVGhlIGNvbnRyYWN0IHRoaXMgcGx1Z2luIGV4cGVjdHMgb2YgdGhlIHByb3ZpZGVyLCB3aGljaCB3aW5zIG92ZXIgdGhlIHByb3ZpZGVyJ3Mgb3duIHdoZW4gc3VwcGxpZWQuXG4gICAqXG4gICAqIFdvcnRoIHN1cHBseWluZywgYW5kIHdvcnRoIGtlZXBpbmcgTkFSUk9XLiBBIG1pZ3JhdGlvbiB1c3VhbGx5IG5lZWRzIG9uZSBtZXRob2QgdGhhdCBoYXMgZXhpc3RlZCBzaW5jZSB0aGVcbiAgICogcHJvdmlkZXIncyBmaXJzdCBjb250cmFjdCB2ZXJzaW9uLCB3aGlsZSB0aGUgc2FtZSBwbHVnaW4gbWF5IHJlYWQgb3RoZXIgcGFydHMgb2YgdGhhdCBBUEkgdGhyb3VnaCBhIG11Y2hcbiAgICogbmV3ZXIgb25lLiBEZWNsYXJpbmcgdGhlIHdpZGVyIGV4cGVjdGF0aW9uIGhlcmUgd291bGQgcmVmdXNlIHRvIG9mZmVyIHRoZSBtaWdyYXRpb24gdG8gYSB1c2VyIG9uIGFuIG9sZGVyXG4gICAqIHByb3ZpZGVyIFx1MjAxNCB3aGljaCBpcyBwcmVjaXNlbHkgdGhlIHVzZXIgd2hvIHN0aWxsIGhhcyBzZXR0aW5ncyB0byBtaWdyYXRlLlxuICAgKi9cbiAgcmVhZG9ubHkgY29udHJhY3Q/OiBQbHVnaW5BcGlDb250cmFjdDtcblxuICAvKipcbiAgICogUmVhZHMgdGhlIHZhbHVlcyBjdXJyZW50bHkgd2FpdGluZyB0byBiZSBoYW5kZWQgb3Zlci5cbiAgICpcbiAgICogQ2FsbGVkIGFmcmVzaCBvbiBldmVyeSBlZGdlIHJhdGhlciB0aGFuIG9uY2UsIHNvIGFuIGltcGxlbWVudGF0aW9uIHNpbXBseSByZWFkcyBpdHMgcGx1Z2luJ3Mgc2V0dGluZ3MuXG4gICAqIFJldHVybiBgbnVsbGAgd2hlbiB0aGVyZSBpcyBub3RoaW5nIHBlbmRpbmcgXHUyMDE0IGFmdGVyIGEgbWlncmF0aW9uIGhhcyBiZWVuIGFwcGxpZWQsIG9yIG9uIGEgdmF1bHQgdGhhdCBuZXZlclxuICAgKiBoYWQgdGhlc2Ugc2V0dGluZ3MgY29uZmlndXJlZC5cbiAgICpcbiAgICogQHJldHVybnMgVGhlIHZhbHVlcyB0byBwcm9wb3NlLCBvciBgbnVsbGAgd2hlbiB0aGVyZSBpcyBub3RoaW5nIHRvIG9mZmVyLlxuICAgKi9cbiAgcmVhZG9ubHkgZ2V0UHJvcG9zZWRTZXR0aW5nczogKCkgPT4gbnVsbCB8IFRNaWdyYXRhYmxlU2V0dGluZ3M7XG5cbiAgLyoqXG4gICAqIFRoZSBzZXR0aW5ncyBjb21wb25lbnQgb2YgdGhlIHBsdWdpbiBtYWtpbmcgdGhlIHByb3Bvc2FsLlxuICAgKlxuICAgKiBUYWtlbiBhcyBhIHdob2xlIGNvbXBvbmVudCByYXRoZXIgdGhhbiBhcyBhIGJhcmUgXCJyZWFkeVwiIGZsYWcgc28gdGhlIGhvc3QgY2Fubm90IGZvcmdldCB0byB3aXJlIHRoZSB3YWl0OlxuICAgKiB3aGF0ZXZlciB7QGxpbmsgZ2V0UHJvcG9zZWRTZXR0aW5nc30gcmVhZHMgaXMgbWVhbmluZ2xlc3MgdW50aWwgdGhpcyBjb21wb25lbnQgaGFzIHJlYWQgYGRhdGEuanNvbmAuXG4gICAqL1xuICByZWFkb25seSBwbHVnaW5TZXR0aW5nc0NvbXBvbmVudDogUGx1Z2luU2V0dGluZ3NDb21wb25lbnRCYXNlPG9iamVjdD47XG5cbiAgLyoqXG4gICAqIFRoZSBgbWFuaWZlc3QuaWRgIG9mIHRoZSBwbHVnaW4gdGhhdCBvd25zIHRoZXNlIHNldHRpbmdzIG5vdywgYXMgbGlzdGVkIGluIE9ic2lkaWFuJ3MgY29tbXVuaXR5IHBsdWdpblxuICAgKiByZWdpc3RyeS5cbiAgICovXG4gIHJlYWRvbmx5IHByb3ZpZGVyUGx1Z2luSWQ6IHN0cmluZztcblxuICAvKipcbiAgICogUmVjb3JkcyB0aGF0IHRoZSBwZW5kaW5nIHZhbHVlcyBoYXZlIGJlZW4gaGFuZGVkIG92ZXIsIHNvIHRoZSBvZmZlciBpcyBub3QgbWFkZSBhZ2Fpbi5cbiAgICpcbiAgICogQ2FsbGVkIE9OTFkgd2hlbiB0aGUgdXNlciBhY3R1YWxseSBhcHBsaWVkIHRoZSBtaWdyYXRpb24uXG4gICAqXG4gICAqIEByZXR1cm5zIEEge0BsaW5rIFByb21pc2V9IHRoYXQgcmVzb2x2ZXMgb25jZSB0aGUgcmV0aXJlbWVudCBpcyBwZXJzaXN0ZWQuXG4gICAqXG4gICAqIEByZW1hcmtzXG4gICAqIEFuIGltcGxlbWVudGF0aW9uIG11c3QgUEVSU0lTVCB0aGUgcmV0aXJlbWVudCBcdTIwMTQgYHBsdWdpblNldHRpbmdzQ29tcG9uZW50LmVkaXRBbmRTYXZlKFx1MjAyNilgLCBub3RcbiAgICogYHNldFByb3BlcnR5KFx1MjAyNilgLiBUaGUgbGF0dGVyIG9ubHkgZWRpdHMgdGhlIGluLW1lbW9yeSBzdGF0ZSwgc28gdGhlIHJldGlyZW1lbnQgaXMgZm9yZ290dGVuIG9uIHRoZSBuZXh0XG4gICAqIHJlbG9hZCBhbmQgdGhlIG1pZ3JhdGlvbiBpcyBvZmZlcmVkIGFnYWluIGZvcmV2ZXIuXG4gICAqL1xuICByZWFkb25seSByZXRpcmVQcm9wb3NlZFNldHRpbmdzOiAoKSA9PiBQcm9taXNhYmxlPHZvaWQ+O1xuXG4gIC8qKlxuICAgKiBUaGUgYG1hbmlmZXN0LmlkYCBvZiB0aGUgcGx1Z2luIG1ha2luZyB0aGUgcHJvcG9zYWwsIHNvIHRoZSBwcm92aWRlcidzIGRpYWxvZyBjYW4gc2F5IHdob3NlIHNldHRpbmdzIHRoZXNlXG4gICAqIGFyZS5cbiAgICovXG4gIHJlYWRvbmx5IHNvdXJjZVBsdWdpbklkOiBzdHJpbmc7XG59XG5cbi8qKlxuICogT2ZmZXJzIHNldHRpbmdzIHRoaXMgcGx1Z2luIHVzZWQgdG8gb3duIHRvIHRoZSBwbHVnaW4gdGhhdCBvd25zIHRoZW0gbm93LlxuICpcbiAqIEB0eXBlUGFyYW0gVE1pZ3JhdGFibGVTZXR0aW5ncyAtIFRoZSBzZXR0aW5ncyB0aGlzIHBsdWdpbiBtYXkgaGFuZCBvdmVyLlxuICovXG5leHBvcnQgY2xhc3MgU2V0dGluZ3NNaWdyYXRpb25Db21wb25lbnQ8VE1pZ3JhdGFibGVTZXR0aW5ncyBleHRlbmRzIG9iamVjdD4gZXh0ZW5kcyBDb21wb25lbnRFeCB7XG4gIHByaXZhdGUgcmVhZG9ubHkgYXBpVmVyc2lvblJhbmdlOiBzdHJpbmc7XG4gIHByaXZhdGUgcmVhZG9ubHkgYXBwOiBBcHA7XG4gIHByaXZhdGUgcmVhZG9ubHkgY29udHJhY3Q6IFBsdWdpbkFwaUNvbnRyYWN0IHwgdW5kZWZpbmVkO1xuICBwcml2YXRlIHJlYWRvbmx5IGdldFByb3Bvc2VkU2V0dGluZ3M6ICgpID0+IG51bGwgfCBUTWlncmF0YWJsZVNldHRpbmdzO1xuICBwcml2YXRlIGlzUHJvcG9zaW5nID0gZmFsc2U7XG4gIHByaXZhdGUgcmVhZG9ubHkgcGx1Z2luU2V0dGluZ3NDb21wb25lbnQ6IFBsdWdpblNldHRpbmdzQ29tcG9uZW50QmFzZTxvYmplY3Q+O1xuICBwcml2YXRlIHJlYWRvbmx5IHByb3ZpZGVyUGx1Z2luSWQ6IHN0cmluZztcbiAgcHJpdmF0ZSByZWFkb25seSByZXRpcmVQcm9wb3NlZFNldHRpbmdzOiAoKSA9PiBQcm9taXNhYmxlPHZvaWQ+O1xuICBwcml2YXRlIHJlYWRvbmx5IHNvdXJjZVBsdWdpbklkOiBzdHJpbmc7XG5cbiAgLyoqXG4gICAqIENyZWF0ZXMgYW4gaW5zdGFuY2Ugb2Yge0BsaW5rIFNldHRpbmdzTWlncmF0aW9uQ29tcG9uZW50fS5cbiAgICpcbiAgICogQHBhcmFtIHBhcmFtcyAtIFRoZSBjb25zdHJ1Y3RvciBwYXJhbWV0ZXJzLlxuICAgKi9cbiAgcHVibGljIGNvbnN0cnVjdG9yKHBhcmFtczogU2V0dGluZ3NNaWdyYXRpb25Db21wb25lbnRDb25zdHJ1Y3RvclBhcmFtczxUTWlncmF0YWJsZVNldHRpbmdzPikge1xuICAgIHN1cGVyKCk7XG4gICAgdGhpcy5hcGlWZXJzaW9uUmFuZ2UgPSBwYXJhbXMuYXBpVmVyc2lvblJhbmdlO1xuICAgIHRoaXMuYXBwID0gcGFyYW1zLmFwcDtcbiAgICB0aGlzLmNvbnRyYWN0ID0gcGFyYW1zLmNvbnRyYWN0O1xuICAgIHRoaXMuZ2V0UHJvcG9zZWRTZXR0aW5ncyA9IHBhcmFtcy5nZXRQcm9wb3NlZFNldHRpbmdzO1xuICAgIHRoaXMucGx1Z2luU2V0dGluZ3NDb21wb25lbnQgPSBwYXJhbXMucGx1Z2luU2V0dGluZ3NDb21wb25lbnQ7XG4gICAgdGhpcy5wcm92aWRlclBsdWdpbklkID0gcGFyYW1zLnByb3ZpZGVyUGx1Z2luSWQ7XG4gICAgdGhpcy5yZXRpcmVQcm9wb3NlZFNldHRpbmdzID0gcGFyYW1zLnJldGlyZVByb3Bvc2VkU2V0dGluZ3M7XG4gICAgdGhpcy5zb3VyY2VQbHVnaW5JZCA9IHBhcmFtcy5zb3VyY2VQbHVnaW5JZDtcbiAgfVxuXG4gIC8qKlxuICAgKiBMb2FkcyB0aGUgY29tcG9uZW50LCB3aXJpbmcgYm90aCBlZGdlcyB0aGF0IGNhbiBtYWtlIGFuIG9mZmVyIHBvc3NpYmxlLlxuICAgKi9cbiAgcHVibGljIG92ZXJyaWRlIG9ubG9hZCgpOiB2b2lkIHtcbiAgICAvLyBOb3RoaW5nIGlzIGdhdGVkIG9uIHRoZSBwZW5kaW5nIHZhbHVlcyBIRVJFLiBUaGUgc2V0dGluZ3MgY29tcG9uZW50IGlzIGEgc2libGluZyB3aG9zZSBvd24gbG9hZCBpcyBzdGlsbFxuICAgIC8vIGluIGZsaWdodCBhdCB0aGlzIHBvaW50LCBzbyBpdCBzdGlsbCBob2xkcyB0aGUgREVGQVVMVFMgXHUyMDE0IHJlYWRpbmcgdGhlIHBlbmRpbmcgdmFsdWVzIG5vdyB3b3VsZCBzZWVcbiAgICAvLyBub3RoaW5nIG9uIGV4YWN0bHkgdGhlIHZhdWx0cyB0aGF0IGhhdmUgc29tZXRoaW5nLCByZWdpc3RlciBubyB3YXRjaCwgYW5kIGxvc2UgdGhlIG1pZ3JhdGlvbiBmb3IgZ29vZC5cbiAgICAvLyBCb3RoIGVkZ2VzIGFyZSB3aXJlZCBpbnN0ZWFkLCBhbmQgYHByb3Bvc2VgIHJlLXJlYWRzIHRoZSB2YWx1ZXMgZWFjaCB0aW1lIGl0IHJ1bnMuXG4gICAgY29uc3QgcmVmID0gd2F0Y2hQbHVnaW5BcGk8U2V0dGluZ3NNaWdyYXRpb25BcGk8VE1pZ3JhdGFibGVTZXR0aW5ncz4+KG5vcm1hbGl6ZU9wdGlvbmFsUHJvcGVydGllczxXYXRjaFBsdWdpbkFwaVBhcmFtcz4oe1xuICAgICAgYXBpVmVyc2lvblJhbmdlOiB0aGlzLmFwaVZlcnNpb25SYW5nZSxcbiAgICAgIGFwcDogdGhpcy5hcHAsXG4gICAgICBjb21wb25lbnQ6IHRoaXMsXG4gICAgICBjb250cmFjdDogdGhpcy5jb250cmFjdCxcbiAgICAgIHBsdWdpbklkOiB0aGlzLnByb3ZpZGVyUGx1Z2luSWRcbiAgICB9KSk7XG5cbiAgICAvLyBEcml2ZW4gYnkgdGhlIHJlZidzIG93biBldmVudCByYXRoZXIgdGhhbiBieSBgd2hlbkF2YWlsYWJsZSgpYCwgZGVsaWJlcmF0ZWx5LiBUaGF0IHdhaXQgYmxvY2tzIGZvciB0ZW5cbiAgICAvLyBzZWNvbmRzIGFuZCB0aGVuIHRocm93cyB3aGVuIHRoZSBwcm92aWRlciBpcyBzaW1wbHkgbm90IGluc3RhbGxlZCwgd2hpY2ggd291bGQgc3RhbGwgdGhpcyBwbHVnaW4ncyBsb2FkXG4gICAgLy8gZm9yIGV2ZXJ5IHVzZXIgd2hvIGRlY2xpbmVzIHRoZSBzdWdnZXN0aW9uLiBXYXRjaGluZyBjb3N0cyBub3RoaW5nIHdoaWxlIHRoZSBwcm92aWRlciBpcyBhYnNlbnQgYW5kXG4gICAgLy8gb2ZmZXJzIHRoZSBtaWdyYXRpb24gdGhlIG1vbWVudCBpdCBhcHBlYXJzIFx1MjAxNCBpbmNsdWRpbmcgcmlnaHQgYWZ0ZXIgdGhlIHVzZXIgaW5zdGFsbHMgaXQgZnJvbSB0aGVcbiAgICAvLyBzdWdnZXN0aW9uIGJhbm5lci5cbiAgICByZWdpc3RlckFzeW5jRXZlbnQoXG4gICAgICB0aGlzLFxuICAgICAgcmVmLm9uKCdjaGFuZ2UnLCAoKSA9PiB7XG4gICAgICAgIHRoaXMuaGFuZGxlQ2hhbmdlKHJlZik7XG4gICAgICB9KVxuICAgICk7XG5cbiAgICAvLyBUaGUgc2Vjb25kIGVkZ2U6IHRoaXMgcGx1Z2luJ3Mgb3duIHNldHRpbmdzIGFycml2aW5nIGZyb20gZGlzay4gSXQgbWF5IGZpcmUgYmVmb3JlIG9yIGFmdGVyIHRoZSBmaXJzdC5cbiAgICByZWdpc3RlckFzeW5jRXZlbnQoXG4gICAgICB0aGlzLFxuICAgICAgdGhpcy5wbHVnaW5TZXR0aW5nc0NvbXBvbmVudC5vbignbG9hZFNldHRpbmdzJywgKCkgPT4ge1xuICAgICAgICB0aGlzLmhhbmRsZUNoYW5nZShyZWYpO1xuICAgICAgfSlcbiAgICApO1xuXG4gICAgdGhpcy5oYW5kbGVDaGFuZ2UocmVmKTtcbiAgfVxuXG4gIHByaXZhdGUgaGFuZGxlQ2hhbmdlKHJlZjogUGx1Z2luQXBpUmVmPFNldHRpbmdzTWlncmF0aW9uQXBpPFRNaWdyYXRhYmxlU2V0dGluZ3M+Pik6IHZvaWQge1xuICAgIGludm9rZUFzeW5jU2FmZWx5KGFzeW5jICgpID0+IHtcbiAgICAgIGF3YWl0IHRoaXMucHJvcG9zZShyZWYudmFsdWUpO1xuICAgIH0pO1xuICB9XG5cbiAgcHJpdmF0ZSBhc3luYyBwcm9wb3NlKGFwaTogbnVsbCB8IFNldHRpbmdzTWlncmF0aW9uQXBpPFRNaWdyYXRhYmxlU2V0dGluZ3M+KTogUHJvbWlzZTx2b2lkPiB7XG4gICAgY29uc3QgcHJvcG9zZWRTZXR0aW5ncyA9IHRoaXMuZ2V0UHJvcG9zZWRTZXR0aW5ncygpO1xuICAgIGlmICghYXBpIHx8IHRoaXMuaXNQcm9wb3NpbmcgfHwgcHJvcG9zZWRTZXR0aW5ncyA9PT0gbnVsbCkge1xuICAgICAgcmV0dXJuO1xuICAgIH1cblxuICAgIC8vIEJvdGggZWRnZXMgY2FuIGZpcmUgd2hpbGUgdGhlIHByb3ZpZGVyJ3MgZGlhbG9nIGlzIG9wZW4sIGFuZCBlYWNoIHdvdWxkIHJhaXNlIGEgc2Vjb25kIG9uZS5cbiAgICB0aGlzLmlzUHJvcG9zaW5nID0gdHJ1ZTtcbiAgICB0cnkge1xuICAgICAgY29uc3QgcmVzdWx0ID0gYXdhaXQgYXBpLm1pZ3JhdGVTZXR0aW5ncyh7XG4gICAgICAgIHByb3Bvc2VkU2V0dGluZ3MsXG4gICAgICAgIHNvdXJjZVBsdWdpbklkOiB0aGlzLnNvdXJjZVBsdWdpbklkXG4gICAgICB9KTtcblxuICAgICAgLy8gQSBjYW5jZWwgaXMgbm90IGFuIGFuc3dlciwgc28gdGhlIHZhbHVlcyBzdGF5IHBlbmRpbmcgYW5kIHRoZSBvZmZlciBjb21lcyBiYWNrIFx1MjAxNCBvbiB0aGUgbmV4dCBsb2FkLCBvclxuICAgICAgLy8gYXMgc29vbiBhcyB0aGUgcHJvdmlkZXIgcmVsb2Fkcy4gT25seSBhbiBhcHBsaWVkIG1pZ3JhdGlvbiByZXRpcmVzIHRoZW0uXG4gICAgICBpZiAocmVzdWx0LmlzQXBwbGllZCkge1xuICAgICAgICBhd2FpdCB0aGlzLnJldGlyZVByb3Bvc2VkU2V0dGluZ3MoKTtcbiAgICAgIH1cbiAgICB9IGZpbmFsbHkge1xuICAgICAgdGhpcy5pc1Byb3Bvc2luZyA9IGZhbHNlO1xuICAgIH1cbiAgfVxufVxuIl0sCiAgIm1hcHBpbmdzIjogIjs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztBQXVCQSxTQUFTLHlCQUF5QjtBQUNsQyxTQUFTLG1DQUFtQztBQVU1QyxTQUFTLHNCQUFzQjtBQUMvQixTQUFTLDBCQUEwQjtBQUNuQyxTQUFTLG1CQUFtQjtBQWtGckIsTUFBTSxtQ0FBdUUsWUFBWTtBQUFBLEVBQzdFO0FBQUEsRUFDQTtBQUFBLEVBQ0E7QUFBQSxFQUNBO0FBQUEsRUFDVCxjQUFjO0FBQUEsRUFDTDtBQUFBLEVBQ0E7QUFBQSxFQUNBO0FBQUEsRUFDQTtBQUFBO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQSxFQU9WLFlBQVksUUFBMEU7QUFDM0YsVUFBTTtBQUNOLFNBQUssa0JBQWtCLE9BQU87QUFDOUIsU0FBSyxNQUFNLE9BQU87QUFDbEIsU0FBSyxXQUFXLE9BQU87QUFDdkIsU0FBSyxzQkFBc0IsT0FBTztBQUNsQyxTQUFLLDBCQUEwQixPQUFPO0FBQ3RDLFNBQUssbUJBQW1CLE9BQU87QUFDL0IsU0FBSyx5QkFBeUIsT0FBTztBQUNyQyxTQUFLLGlCQUFpQixPQUFPO0FBQUEsRUFDL0I7QUFBQTtBQUFBO0FBQUE7QUFBQSxFQUtnQixTQUFlO0FBSzdCLFVBQU0sTUFBTSxlQUEwRCw0QkFBa0Q7QUFBQSxNQUN0SCxpQkFBaUIsS0FBSztBQUFBLE1BQ3RCLEtBQUssS0FBSztBQUFBLE1BQ1YsV0FBVztBQUFBLE1BQ1gsVUFBVSxLQUFLO0FBQUEsTUFDZixVQUFVLEtBQUs7QUFBQSxJQUNqQixDQUFDLENBQUM7QUFPRjtBQUFBLE1BQ0U7QUFBQSxNQUNBLElBQUksR0FBRyxVQUFVLE1BQU07QUFDckIsYUFBSyxhQUFhLEdBQUc7QUFBQSxNQUN2QixDQUFDO0FBQUEsSUFDSDtBQUdBO0FBQUEsTUFDRTtBQUFBLE1BQ0EsS0FBSyx3QkFBd0IsR0FBRyxnQkFBZ0IsTUFBTTtBQUNwRCxhQUFLLGFBQWEsR0FBRztBQUFBLE1BQ3ZCLENBQUM7QUFBQSxJQUNIO0FBRUEsU0FBSyxhQUFhLEdBQUc7QUFBQSxFQUN2QjtBQUFBLEVBRVEsYUFBYSxLQUFvRTtBQUN2RixzQkFBa0IsWUFBWTtBQUM1QixZQUFNLEtBQUssUUFBUSxJQUFJLEtBQUs7QUFBQSxJQUM5QixDQUFDO0FBQUEsRUFDSDtBQUFBLEVBRUEsTUFBYyxRQUFRLEtBQXNFO0FBQzFGLFVBQU0sbUJBQW1CLEtBQUssb0JBQW9CO0FBQ2xELFFBQUksQ0FBQyxPQUFPLEtBQUssZUFBZSxxQkFBcUIsTUFBTTtBQUN6RDtBQUFBLElBQ0Y7QUFHQSxTQUFLLGNBQWM7QUFDbkIsUUFBSTtBQUNGLFlBQU0sU0FBUyxNQUFNLElBQUksZ0JBQWdCO0FBQUEsUUFDdkM7QUFBQSxRQUNBLGdCQUFnQixLQUFLO0FBQUEsTUFDdkIsQ0FBQztBQUlELFVBQUksT0FBTyxXQUFXO0FBQ3BCLGNBQU0sS0FBSyx1QkFBdUI7QUFBQSxNQUNwQztBQUFBLElBQ0YsVUFBRTtBQUNBLFdBQUssY0FBYztBQUFBLElBQ3JCO0FBQUEsRUFDRjtBQUNGOyIsCiAgIm5hbWVzIjogW10KfQo=

package/dist/lib/esm/components/syntax-highlighting-component.d.mts

@@ -0,0 +1,149 @@
+/// <reference path="../library.d.mts" />
+/**
+ * @file
+ *
+ * Contains class {@link SyntaxHighlightingComponent} that registers syntax highlighting languages.
+ *
+ * Obsidian highlights code in two independent places, through two separate registries, and a plugin adding
+ * its own language usually has to touch both:
+ *
+ * - **Prism** (`prism.languages[language]`) highlights code in reading view and in every `<pre><code>` the
+ *   library renders — including the {@link CodeHighlighterComponent} settings field.
+ * - **The CodeMirror 5 mode registry** (`window.CodeMirror.modes[language]`) highlights a fenced code block
+ *   inside the editor.
+ *
+ * The CodeMirror 5 half looks like legacy that should be migrated to CodeMirror 6. **It is not** — verified
+ * against the Obsidian 1.13.4 runtime:
+ *
+ * - Obsidian's own CodeMirror 6 editor language is a bridged CodeMirror 5 mode:
+ *   `StreamLanguage.define(CodeMirror.getMode({}, { name: 'hypermd' }))`.
+ * - Obsidian registers that `hypermd` mode through `window.CodeMirror.defineMode` with
+ *   `fencedCodeBlockHighlighting: true`, and that option resolves each fence's language through the
+ *   **CodeMirror 5 mode registry**.
+ * - There is no public or internal CodeMirror 6 language-registration API for fences.
+ *
+ * So `window.CodeMirror.defineMode` is the sanctioned extension point, not legacy debt. Do not reopen this
+ * as a migration.
+ *
+ * Teardown REMOVES the mode rather than redefining it to `null`. Plugins predating this component redefined
+ * the mode to `null` on unload, because it was unclear whether CodeMirror's `getMode` needs the entry to
+ * stay present. It does not — verified against a live Obsidian 1.13.4 by
+ * `syntax-highlighting-component.obsidian.integration.test.ts`: after the entry is deleted, the fence
+ * renders its text with no error and drops back to the exact token count it had before the language was
+ * ever registered.
+ */
+import type { Grammar, PrismModule } from '@obsidian-typings/obsidian-public-latest';
+import { ComponentEx } from './component-ex.mjs';
+/**
+ * The loaded Prism module, handed to a grammar factory.
+ */
+export interface SyntaxHighlightingComponentGrammarFactoryParams {
+    /**
+     * The loaded Prism module.
+     */
+    readonly prism: PrismModule;
+    /**
+     * Returns the grammar of an already registered Prism language, for nesting into the built grammar.
+     *
+     * @param language - The language to look up.
+     * @returns The grammar of the language.
+     * @throws An {@link Error} if the language is not registered.
+     */
+    readonly requirePrismLanguage: (language: string) => Grammar;
+}
+/**
+ * A grammar, the name of an already registered language to alias, or a factory that builds the grammar from
+ * the loaded Prism module.
+ */
+export type SyntaxHighlightingComponentGrammarSource = ((params: SyntaxHighlightingComponentGrammarFactoryParams) => Grammar) | Grammar | string;
+/**
+ * Parameters for {@link SyntaxHighlightingComponent.registerCodeBlockLanguage}.
+ */
+export interface SyntaxHighlightingComponentRegisterCodeBlockLanguageParams {
+    /**
+     * The CodeMirror 5 mode name or MIME type the editor highlights the fence as, e.g. `text/typescript`.
+     */
+    readonly editorMode: string;
+    /**
+     * The fence language, e.g. the `foo` in a ` ```foo ` code block.
+     */
+    readonly language: string;
+    /**
+     * The grammar highlighting the fence in reading view. Omit when the fence is replaced in reading view —
+     * e.g. a fence rendered as a button.
+     */
+    readonly prismGrammar?: SyntaxHighlightingComponentGrammarSource | undefined;
+}
+/**
+ * Parameters for {@link SyntaxHighlightingComponent.registerPrismLanguage}.
+ */
+export interface SyntaxHighlightingComponentRegisterPrismLanguageParams {
+    /**
+     * The grammar to register.
+     */
+    readonly grammar: SyntaxHighlightingComponentGrammarSource;
+    /**
+     * The language to register the grammar as.
+     */
+    readonly language: string;
+}
+/**
+ * A component that registers and unregisters syntax highlighting languages.
+ *
+ * @remarks
+ * Every registration is undone when the component is unloaded: the previous entry is restored if the
+ * language was already registered, otherwise the entry is removed.
+ */
+export declare class SyntaxHighlightingComponent extends ComponentEx {
+    /**
+     * Registers a fenced code block language, highlighting it in the editor and, optionally, in reading view.
+     *
+     * @param params - The parameters for registering the language.
+     * @returns A {@link Promise} that resolves when the language is registered.
+     *
+     * @example
+     * ```ts
+     * await component.registerCodeBlockLanguage({
+     *   editorMode: 'text/typescript',
+     *   language: 'my-language',
+     *   prismGrammar: 'typescript'
+     * });
+     * ```
+     */
+    registerCodeBlockLanguage(params: SyntaxHighlightingComponentRegisterCodeBlockLanguageParams): Promise<void>;
+    /**
+     * Registers a Prism language, highlighting it everywhere Prism renders code — reading view and the
+     * {@link CodeHighlighterComponent} settings field.
+     *
+     * @param params - The parameters for registering the language.
+     * @returns A {@link Promise} that resolves when the language is registered.
+     *
+     * @example
+     * ```ts
+     * await component.registerPrismLanguage({
+     *   grammar: {
+     *     keyword: /\bfoo\b/
+     *   },
+     *   language: 'my-language'
+     * });
+     * ```
+     */
+    registerPrismLanguage(params: SyntaxHighlightingComponentRegisterPrismLanguageParams): Promise<void>;
+    /**
+     * Returns the grammar of an already registered Prism language.
+     *
+     * @param prism - The loaded Prism module.
+     * @param language - The language to look up.
+     * @returns The grammar of the language.
+     * @throws An {@link Error} if the language is not registered.
+     */
+    private requirePrismLanguage;
+    /**
+     * Resolves a grammar source into the grammar to register.
+     *
+     * @param prism - The loaded Prism module.
+     * @param grammarSource - The grammar source to resolve.
+     * @returns The resolved grammar.
+     */
+    private resolveGrammar;
+}