### Usage example with BBoxHelper

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/geometry-helpers.md

Example of using BBoxHelper to combine and enlarge bounding boxes, and to move a point in a direction. Note: imports BBoxHelper, not SvgPathHelper.

```typescript
import BBoxHelper from "src/utils/bbox-helper"

// A padded box around two boxes
const bbox = BBoxHelper.combineBBoxes([boxA, boxB])
const padded = BBoxHelper.enlargeBBox(bbox, 20)

// Move a point out of a node before routing
const startPos = BBoxHelper.moveInDirection(handlePos, 'right', 10)
```

--------------------------------

### Usage examples for TaskQueue and HashHelper

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/misc-helpers.md

Shows how to use TaskQueue to queue asynchronous tasks and HashHelper to compute a hash from a file's binary data.

```TypeScript
import TaskQueue from "src/utils/task-queue"
import HashHelper from "src/utils/hash-helper"

const queue = new TaskQueue()
queue.setOnFinished(() => console.log("drained"))
await queue.add(() => longRunningWork())

const hash = await HashHelper.getBytesHash(await file.vault.readBinary(file))
```

--------------------------------

### Programmatic construction example

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/advanced-canvas-embed.md

Example of importing the class and constructing an instance with the required context, file, and subpath, then calling load(). This is shown as the programmatic path used by EmbedPatcher.

```typescript
import AdvancedCanvasEmbed from "src/advanced-canvas-embed"

// Called by EmbedPatcher for .canvas embeds with a subpath
const embed = new AdvancedCanvasEmbed(context, file, "#node-abc123")
embed.load()
```

--------------------------------

### Usage example with SvgPathHelper

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/geometry-helpers.md

Example of using SvgPathHelper.pathArrayToRoundedSvgPath to generate a rounded SVG path. The expected output is shown in a comment.

```typescript
import SvgPathHelper from "src/utils/svg-path-helper"

const d = SvgPathHelper.pathArrayToRoundedSvgPath(
  [{ x: 0, y: 0 }, { x: 100, y: 0 }, { x: 100, y: 100 }],
  5
)
// -> "M 0 0 L 95 0 A 5 5 0 0 1 100 5 L 100 100"
```

--------------------------------

### CSS config format example

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/css-styles-config-manager.md

Shows the CSS comment syntax that defines a style config with key, label, and options. The validator requires key, label, options array, each option with icon/label/value, and exactly one option with a null value.

```css
/* @advanced-canvas-node-style
key: validation-state
label: Validation State
options:
  -
    label: Stateless
    value: null
    icon: circle-help
  -
    label: Approved
    value: approved
    icon: circle-check
*/

/* @advanced-canvas-edge-style ...  (same structure) */
```

--------------------------------

### Patcher constructor

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/patcher.md

Stores the plugin instance and immediately fires `void this.patch()`. Subclasses start patching as soon as they are constructed by the plugin's onload().

```APIDOC
## Class: Patcher

### Constructor

```ts
constructor(plugin: AdvancedCanvasPlugin)
```

### Description
Stores `plugin` and immediately fires `void this.patch()`. Subclasses therefore start patching as soon as they are constructed by the plugin's `onload()`.

### Parameters
- **plugin** (`AdvancedCanvasPlugin`) - Required - The plugin instance.
```

--------------------------------

### Accessing Advanced Canvas plugin from another plugin

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/advanced-canvas-plugin.md

Shows how to retrieve the Advanced Canvas plugin instance from another plugin and call its methods. The example checks if the plugin exists, enables debug mode, gets the current canvas, and logs its data.

```ts
// From another plugin's code
const ac = this.app.plugins.plugins["advanced-canvas"]
if (ac) {
  ac.enableDebugMode()
  const canvas = ac.getCurrentCanvas()
  console.log(canvas?.getData())
}
```

--------------------------------

### Usage example with GET_NODE_CSS_STYLES_MANAGER

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/css-styles-config-manager.md

Imports the factory, creates a manager, and calls getStyles() to retrieve cached StyleAttribute[] configs. The cache invalidates on the 'css-change' event.

```typescript
import { GET_NODE_CSS_STYLES_MANAGER } from "src/canvas-extensions/advanced-styles/node-styles"

const manager = GET_NODE_CSS_STYLES_MANAGER(plugin)
const styles = manager.getStyles()   // StyleAttribute[] (cached)
// invalidates on 'css-change'
```

--------------------------------

### CommandsCanvasExtension class definition

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/canvas-extensions-3-workflow-ui.md

Defines the CommandsCanvasExtension class that extends CanvasExtension. It includes methods for creating text/file nodes, cloning, expanding, flipping, navigating, and getting the next node. The isEnabled method returns 'commandsFeatureEnabled'.

```typescript
type Direction = 'up' | 'down' | 'left' | 'right'

export default class CommandsCanvasExtension extends CanvasExtension {
  isEnabled() { return 'commandsFeatureEnabled' as const }
  init()
  private createTextNode(canvas: Canvas)
  private async createFileNode(canvas: Canvas, file?: TFile)
  private cloneNode(canvas: Canvas, cloneDirection: Direction)
  private expandNode(canvas: Canvas, expandDirection: Direction)
  private flipSelection(canvas: Canvas, horizontally: boolean)
  private navigate(canvas: Canvas, direction: Direction)
  private getNextNode(canvas: Canvas, direction: Direction)
}
```

--------------------------------

### init() (abstract)

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/canvas-extension.md

Abstract method that initializes the feature. Registers commands, workspace event listeners, vault listeners, and menu entries.

```APIDOC
## init() (abstract)

### Description
Abstract method that initializes the feature. Registers commands, workspace event listeners, vault listeners, and menu entries.

### Method
init

### Signature
abstract init(): void

### Returns
- **void** - No return value.

### Usage
Subclasses use this.plugin.registerEvent(this.plugin.app.workspace.on(...)), this.plugin.addCommand(...), this.plugin.register(...) and this.plugin.app.vault.on(...).
```

--------------------------------

### Using AbstractSelectionModal, FileNameModal, and FileSelectModal

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/modals.md

Shows how to use the modal helper classes to prompt for free-text input, a new canvas file name, or file selection. The `promise` property resolves with the user's selection.

```ts
import { AbstractSelectionModal, FileNameModal, FileSelectModal } from "src/utils/modal-helper"

// Free-text prompt (used e.g. for node template labels)
const label = await new AbstractSelectionModal(app, "Set template label (optional)", [], true).promise

// New canvas file name (used by encapsulate)
const path = await new FileNameModal(app, "Design", "canvas").promise

// Pick an existing PDF (or create any file — used by commands)
const pdf = await new FileSelectModal(app, /^pdf$/).promise
const anyFile = await new FileSelectModal(app, undefined, true).promise
```

--------------------------------

### Example CSS for validation-state custom attribute

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/README.md

Example CSS styling for the validation-state custom attribute. Adds icons to node content based on the attribute value.

```css
.canvas-node[data-validation-state] .canvas-node-content::after {
  content: "";
  position: absolute;
  top: 10px;
  right: 10px;
  font-size: 1em;
}

.canvas-node[data-validation-state="approved"] .canvas-node-content::after {
  content: "✔️";
}

.canvas-node[data-validation-state="pending"] .canvas-node-content::after {
  content: "⏳";
}

.canvas-node[data-validation-state="rejected"] .canvas-node-content::after {
  content: "❌";
}
```

--------------------------------

### SettingsManager.addSettingsTab()

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/settings-manager.md

Creates the settings tab and registers it with the plugin.

```APIDOC
## addSettingsTab()

### Description
Creates the `AdvancedCanvasPluginSettingTab` and registers it via `plugin.addSettingTab(...)`.

### Method
addSettingsTab

### Signature
`addSettingsTab(): void`

### Parameters
None.

### Return Value
`void`

### Example
```ts
settingsManager.addSettingsTab();
```
```

--------------------------------

### SettingsManager.loadSettings()

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/settings-manager.md

Loads settings from disk, merges them with defaults, and triggers the 'advanced-canvas:settings-changed' event.

```APIDOC
## loadSettings()

### Description
Loads settings from disk by merging the data from `plugin.loadData()` over `DEFAULT_SETTINGS_VALUES`, stores the result, and triggers the workspace event `advanced-canvas:settings-changed`.

### Method
loadSettings

### Signature
`async loadSettings(): Promise<void>`

### Parameters
None.

### Return Value
`Promise<void>`

### Example
```ts
await settingsManager.loadSettings();
```
```

--------------------------------

### init() abstract method

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/canvas-extension.md

Abstract method that registers commands, workspace event listeners, vault listeners, and menu entries. Subclasses use this.plugin.registerEvent, addCommand, register, and app.vault.on.

```TypeScript
abstract init(): void
```

--------------------------------

### createCardMenuOption signature

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/canvas-helper.md

Creates a draggable card-menu button (div.canvas-card-menu-button.mod-draggable). Click places node at center via onPlaced; pointerdown starts temp-node drag; contextmenu calls onRightClick.

```TypeScript
static createCardMenuOption(canvas: Canvas, menuOption: MenuOption, previewNodeSize: () => Size, onPlaced: (canvas: Canvas, pos: Position) => void, onRightClick?: (e: MouseEvent) => void): HTMLElement
```

--------------------------------

### Validate a style attribute with styleAttributeValidator

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/style-config.md

Validates a style attribute definition for CSS-based configs. The validator is used by CssStylesConfigManager; the attributes are part of the public data model. The example shows that the key is camel-cased in the parsed result.

```ts
import { styleAttributeValidator, StyleAttribute } from "src/canvas-extensions/advanced-styles/style-config"

const parsed = styleAttributeValidator({
  key: "validation-state",
  label: "Validation State",
  options: [
    { icon: "circle-help", label: "Stateless", value: null },
    { icon: "circle-check", label: "Approved", value: "approved" },
  ],
})
// parsed.key === "validationState" (camel-cased)
```

--------------------------------

### Node and MinHeap helper classes

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/edge-pathfinding.md

File-private helper classes used by EdgePathfindingAStar. Node stores grid coordinates and costs; MinHeap is a min-heap keyed by fCost for efficient node selection.

```ts
class Node {
  x: number
  y: number
  gCost: number
  hCost: number
  fCost: number
  parent: Node | null
  constructor(x: number, y: number)
}

class MinHeap {   // min-heap keyed by fCost
  get size(): number
  push(node: Node): void
  pop(): Node | null
}
```

--------------------------------

### SuggestManager and Suggestion interfaces

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/types.md

Interfaces for the SuggestManager plugin, exposing app, source path, and a method to get heading suggestions. The Suggestion interface describes a heading suggestion with file, heading, level, matches, and score.

```ts
export default interface SuggestManager {
  app: App
  getSourcePath: () => string
  getHeadingSuggestions: (context: App, path: string, subpath: string) => Promise<Suggestion[]>
}
export interface Suggestion {
  file: TFile
  heading: string
  level: number
  matches: [number, number][]
  path: string
  subpath: string
  score: number
  type: "heading"
}
```

--------------------------------

### Directly instantiate EdgePathfindingSquare

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/edge-pathfinding.md

Directly creates an EdgePathfindingSquare instance with the required constructor arguments and applies the resulting path to the edge. The path is used only if it exists.

```ts
import EdgePathfindingSquare from "src/canvas-extensions/advanced-styles/edge-pathfinding-methods/pathfinding-square"

const path = new EdgePathfindingSquare(
  plugin, canvas,
  fromNodeBBox, fromPos, fromBBoxSidePos, 'right',
  toNodeBBox, toPos, toBBoxSidePos, 'left'
).getPath()

if (path) {
  edge.center = path.center
  edge.path.interaction.setAttr("d", path.svgPath)
  edge.path.display.setAttr("d", path.svgPath)
}
```

--------------------------------

### createFileSnapshot(path: string, content: string)

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/advanced-canvas-plugin.md

Uses the Obsidian file-recovery core plugin to force-add a snapshot entry for the given path and content. Returns undefined when the file-recovery plugin is unavailable.

```APIDOC
## createFileSnapshot(path: string, content: string)

### Description
Uses the Obsidian file-recovery core plugin to force-add a snapshot entry for the given path and content. Returns undefined when the file-recovery plugin is unavailable.

### Method
createFileSnapshot

### Parameters
- **path** (string) - Required - The file path for which to create a snapshot.
- **content** (string) - Required - The content to store in the snapshot.

### Returns
void (undefined) when the file-recovery plugin is unavailable.
```

--------------------------------

### Define custom canvas color with --canvas-color-X

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/configuration.md

Defines a custom canvas color. Obsidian versions < 1.13 require comma-separated RGB (--canvas-color-X: 0, 255, 0;). Custom colors appear in the picker, can extend defaultTextNodeColor/defaultEdgeColor ranges, and get .mod-canvas-color-X classes.

```css
body {
    /* X starts at 7 (1–6 are Obsidian defaults) */
    --canvas-color-X: rgb(0, 255, 0);
}
```

--------------------------------

### FileSelectModal

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/modals.md

Creates a modal that prompts the user to select a file. The promise resolves with the selected file or null if cancelled.

```APIDOC
## FileSelectModal

### Description
Creates a modal that prompts the user to select a file. The promise resolves with the selected file or null if cancelled.

### Constructor
`new FileSelectModal(app, extensionRegex, allowAnyFile)`

### Parameters
- **app** (App) - Required - The Obsidian app instance.
- **extensionRegex** (RegExp | undefined) - Optional - Regular expression to filter files by extension (e.g., /^pdf$/).
- **allowAnyFile** (boolean) - Optional - Whether to allow selecting any file.

### Properties
- **promise** (Promise<TFile | null>) - Resolves with the selected file, or null if cancelled. Never rejects.

### Usage Example
```ts
const pdf = await new FileSelectModal(app, /^pdf$/).promise
const anyFile = await new FileSelectModal(app, undefined, true).promise
```

### Error Handling
The promise never rejects; it resolves with the selection or null.
```

--------------------------------

### Style canvas nodes with data attributes (CSS)

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/dataset-exposers.md

Use this CSS to customize the appearance of canvas nodes based on their data attributes. The first rule rotates diamond-shaped nodes, the second adds a play icon to start nodes, and the third highlights approved nodes with a green outline.

```css
.canvas-node[data-shape="diamond"] {
  border-radius: 0;
  transform: rotate(45deg);
}

.canvas-node[data-is-start-node] .canvas-node-content::after {
  content: "▶";
}

.canvas-node[data-targetValidationState="approved"] {
  outline: 2px solid green;
}
```

--------------------------------

### BBoxHelper.direction(side)

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/geometry-helpers.md

Returns 1 for 'right' or 'bottom', otherwise -1.

```APIDOC
## BBoxHelper.direction(side)

### Description
Returns `1` for `'right'`/`'bottom'`, otherwise `-1`.

### Method
Static method

### Signature
`static direction(side: Side): number`

### Parameters
- **side** (`Side`) - Required - The side to get the direction for.

### Return
`number`
```

--------------------------------

### createControlMenuButton(menuOption)

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/canvas-helper.md

Creates a control menu button element with icon and tooltip. Clicking invokes the provided callback.

```APIDOC
## createControlMenuButton(menuOption)

### Description
Creates a `div.canvas-control-item` with the given id, icon (`setIcon`) and tooltip (`setTooltip`, placement `left`). Clicking invokes `menuOption.callback?.()`.

### Method
Static method

### Signature
```ts
static createControlMenuButton(menuOption: MenuOption): HTMLElement
```

### Parameters
- **menuOption** (MenuOption) - Required - The menu option configuration.
  - **id** (string) - Optional - Unique identifier for the button.
  - **label** (string) - Required - The label/tooltip text.
  - **icon** (string) - Required - The icon identifier.
  - **callback** (() => void) - Optional - Function invoked on click.

### Returns
- HTMLElement - The created control menu button element.
```

--------------------------------

### tryPatchWorkspacePrototype(plugin, getTarget, patches, uninstallers)

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/patcher.md

Attempts patchPrototype immediately; if the target is not available yet, listens once for the workspace layout-change event and retries.

```APIDOC
## tryPatchWorkspacePrototype(plugin, getTarget, patches, uninstallers)

### Description
Attempts patchPrototype immediately; if the target is not available yet, listens once for the workspace layout-change event and retries.

### Method
static async

### Signature
```ts
static tryPatchWorkspacePrototype<T>(
  plugin: Plugin,
  getTarget: () => T | undefined,
  patches: FunctionPatchObject<T>,
  uninstallers?: Array<() => void>
): Promise<T>
```

### Parameters
- **plugin** (Plugin) - Required - Used to register the uninstaller and event.
- **getTarget** (() => T | undefined) - Required - Function that returns the target object or undefined if not yet available.
- **patches** (FunctionPatchObject<T>) - Required - Map of patch wrappers.
- **uninstallers** (Array<() => void>) - Optional - Received uninstaller callbacks.

### Return Value
- **Promise<T>** - Resolves with the patched object.

### Behavior
Attempts patchPrototype immediately; if the target is not available yet, listens once for the workspace layout-change event (registered through plugin.registerEvent) and retries.
```

--------------------------------

### FileSelectModal renderSuggestion method

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/modals.md

Method signature for renderSuggestion. It renders the path with a trailing .md stripped.

```ts
renderSuggestion(path: string, el: HTMLElement)
```

--------------------------------

### patchOnce(plugin, object, patches)

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/patcher.md

Patches with wrappers that resolve once the patched method runs for the first time, then uninstalls all wrappers.

```APIDOC
## patchOnce(plugin, object, patches)

### Description
Patches with wrappers that resolve once the patched method runs for the first time, then uninstalls all wrappers.

### Method
static async

### Signature
```ts
static async patchOnce<T, V>(
  plugin: Plugin,
  object: T | undefined,
  patches: (resolve: (vaule: V) => void) => FunctionPatchObject<T>
): Promise<V>
```

### Parameters
- **plugin** (Plugin) - Required - See patch.
- **object** (T | undefined) - Required - See patch.
- **patches** ((resolve: (value: V) => void) => FunctionPatchObject<T>) - Required - Factory receiving a resolver; wrappers call it to observe the first invocation.

### Return Value
- **Promise<V>** - The value passed to resolve.
```

--------------------------------

### createPopupMenuOption(menuOption)

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/canvas-helper.md

Creates a popup menu button with icon and tooltip. Clicking invokes the callback.

```APIDOC
## createPopupMenuOption(menuOption)

### Description
Creates a `button.clickable-icon` with icon/tooltip (placement `top`); click invokes `callback`.

### Method
Static method

### Signature
```ts
static createPopupMenuOption(menuOption: MenuOption): HTMLElement
```

### Parameters
- **menuOption** (MenuOption) - Required - The menu option configuration.
  - **id** (string) - Optional - Unique identifier.
  - **label** (string) - Required - The label/tooltip text.
  - **icon** (string) - Required - The icon identifier.
  - **callback** (() => void) - Optional - Function invoked on click.

### Returns
- HTMLElement - The created popup menu button element.
```

--------------------------------

### BBoxHelper.combineBBoxes(bboxes)

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/geometry-helpers.md

Returns the union of all input boxes, computing the minimum of all minX/minY and maximum of all maxX/maxY.

```APIDOC
## BBoxHelper.combineBBoxes(bboxes)

### Description
Returns the union of all boxes: minimum of all `minX`/`minY`, maximum of all `maxX`/`maxY`.

### Method
Static method

### Signature
`static combineBBoxes(bboxes: BBox[]): BBox`

### Parameters
- **bboxes** (`BBox[]`) - Required - Input boxes.

### Return
`BBox`
```

--------------------------------

### FileNameModal

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/modals.md

Creates a modal that prompts the user for a new file name. The promise resolves with the entered path or null if cancelled.

```APIDOC
## FileNameModal

### Description
Creates a modal that prompts the user for a new file name. The promise resolves with the entered path or null if cancelled.

### Constructor
`new FileNameModal(app, defaultName, extension)`

### Parameters
- **app** (App) - Required - The Obsidian app instance.
- **defaultName** (string) - Required - Default file name.
- **extension** (string) - Required - File extension (e.g., "canvas").

### Properties
- **promise** (Promise<string | null>) - Resolves with the entered path, or null if cancelled. Never rejects.

### Usage Example
```ts
const path = await new FileNameModal(app, "Design", "canvas").promise
```

### Error Handling
The promise never rejects; it resolves with the selection or null.
```

--------------------------------

### AbstractSelectionModal

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/modals.md

Creates a modal that prompts the user for free-text input. The promise resolves with the entered text or null if cancelled.

```APIDOC
## AbstractSelectionModal

### Description
Creates a modal that prompts the user for free-text input. The promise resolves with the entered text or null if cancelled.

### Constructor
`new AbstractSelectionModal(app, placeholder, items, allowEmpty)`

### Parameters
- **app** (App) - Required - The Obsidian app instance.
- **placeholder** (string) - Required - Placeholder text for the input field.
- **items** (string[]) - Required - List of items to display (can be empty).
- **allowEmpty** (boolean) - Required - Whether empty input is allowed.

### Properties
- **promise** (Promise<string | null>) - Resolves with the entered text, or null if cancelled. Never rejects.

### Usage Example
```ts
const label = await new AbstractSelectionModal(app, "Set template label (optional)", [], true).promise
```

### Error Handling
The promise never rejects; it resolves with the selection or null.
```

--------------------------------

### patch(plugin, object, patches, prototype, uninstallers)

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/patcher.md

Core entry point for patching an object or its prototype. Returns null if the object is falsy, otherwise applies the patches and registers the uninstaller.

```APIDOC
## patch(plugin, object, patches, prototype, uninstallers)

### Description
Core entry point for patching an object or its prototype. Returns null if the object is falsy, otherwise applies the patches and registers the uninstaller.

### Method
static

### Signature
```ts
static patch<T>(plugin: Plugin, object: T | undefined, patches: FunctionPatchObject<T>, prototype = false, uninstallers?: Array<() => void>): T | null
```

### Parameters
- **plugin** (Plugin) - Required - Used to register the uninstaller.
- **object** (T | undefined) - Required - Target (may be undefined → returns null).
- **patches** (FunctionPatchObject<T>) - Required - Map of patch wrappers.
- **prototype** (boolean) - Optional, default false - Patch the constructor prototype instead of the instance.
- **uninstallers** (Array<() => void>) - Optional - Received uninstaller callbacks.

### Return Value
- **T | null** - null when object is undefined, otherwise object.

### Behavior
1. Returns null when object is falsy.
2. Selects the target: object.constructor.prototype when prototype === true, otherwise object itself.
3. For every patch flagged with __overrideExisting, throws Error(`Method ${String(key)} does not exist on target`) when typeof target[key] !== 'function'.
4. Applies the patches via around(target, patches).
5. Records the uninstaller in uninstallers (if provided) and registers it with plugin.register(uninstaller).
```

--------------------------------

### FileNameModal getSuggestions method

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/modals.md

Method signature for getSuggestions. It appends the file extension to the query (query + '.' + fileExtension) and prefixes with parentPath/ when non-empty. Suggestions that already exist in the vault are filtered out; empty queries return an empty array.

```ts
getSuggestions(query: string): string[]
```

--------------------------------

### CanvasHelper: Create control menu button and select outgoing edges

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/canvas-helper.md

Imports CanvasHelper and demonstrates two operations: adding a 'focus mode' toggle button to the control menu and selecting all outgoing edges of the current selection. The button is added to the parent element of the quick settings button.

```typescript
import CanvasHelper from "src/utils/canvas-helper"

// Add a "focus mode" toggle to the control menu
const button = CanvasHelper.createControlMenuButton({
  id: 'focus-mode-toggle',
  label: 'Focus Mode',
  icon: 'focus',
  callback: () => toggleFocus(canvas)
})
CanvasHelper.addControlMenuButton(canvas.quickSettingsButton.parentElement, button)

// Select all outgoing edges of the current selection
CanvasHelper.selectEdgesForNodes(canvas, 'outgoing')
```

--------------------------------

### getSettingDefinitions() method signature

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/settings-manager.md

Declares the entire settings UI using Obsidian's declarative SettingDefinitionItem API. Returns an array of SettingDefinitionItem objects. The visible predicate of nested pages reads the parent toggle state through getControlValue(...). Dropdown options are built from settings union types.

```TypeScript
override getSettingDefinitions(): SettingDefinitionItem[]
```

--------------------------------

### getSetting method signature

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/settings-manager.md

Type-safe getter signature that returns the value for a given settings key.

```typescript
getSetting<T extends keyof AdvancedCanvasPluginSettingsValues>(key: T): AdvancedCanvasPluginSettingsValues[T]
```

--------------------------------

### Patcher.tryPatchWorkspacePrototype

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/patcher.md

Static method to try patching the workspace prototype.

```APIDOC
## Method: tryPatchWorkspacePrototype (static)

### Description
Static method to try patching the workspace prototype.

### Signature
```ts
static tryPatchWorkspacePrototype<T>(plugin: Plugin, getTarget: () => T | undefined, patches: FunctionPatchObject<T>, uninstallers?: Array<() => void>): Promise<T>
```

### Parameters
- **plugin** (`Plugin`) - Required - The plugin instance.
- **getTarget** (`() => T | undefined`) - Required - A function that returns the target object.
- **patches** (`FunctionPatchObject<T>`) - Required - The patches to apply.
- **uninstallers** (`Array<() => void>`) - Optional - Uninstaller functions.

### Return
`Promise<T>`
```

--------------------------------

### addSettingsTab method signature

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/settings-manager.md

Signature for the addSettingsTab method. Creates and registers the settings tab.

```typescript
addSettingsTab()
```

--------------------------------

### BBoxHelper.enlargeBBox(bbox, padding)

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/geometry-helpers.md

Grows the box by the specified padding on all four sides.

```APIDOC
## BBoxHelper.enlargeBBox(bbox, padding)

### Description
Grows the box by `padding` on all four sides.

### Method
Static method

### Signature
`static enlargeBBox(bbox: BBox, padding: number): BBox`

### Parameters
- **bbox** (`BBox`) - Required - The box to enlarge.
- **padding** (`number`) - Required - The padding amount.

### Return
`BBox`
```

--------------------------------

### waitForMapValueLookup method signature

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/patcher.md

Wraps map[viewType] with around(...) so that the first time the view type is looked up, patch(view) runs on the returned view. Resolves with the patched view and uninstalls the wrapper.

```typescript
protected static async waitForMapValueLookup<T>(map: Record<string, unknown>, viewType: string, patch: (view: T) => void): Promise<T>
```

--------------------------------

### FileSelectModal

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/modals.md

A SuggestModal for selecting an existing file or creating a new one. It filters vault files by extension and can suggest a new file when no matches are found.

```APIDOC
## FileSelectModal

### Description
A SuggestModal for selecting an existing file or creating a new one. It filters vault files by extension and can suggest a new file when no matches are found.

### Constructor

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| app | `App` | yes | — | — |
| extensionsRegex | `RegExp` | no | `/.*/` | Filters vault files by extension match; e.g. `/^pdf$/`. |
| suggestNewFile | `boolean` | no | `false` | When `true`, the typed query is offered as a new-file suggestion; pressing `Shift+Enter` creates the file. |

### Methods

#### getSuggestions(query)

```ts
getSuggestions(query: string): string[]
```

Case-insensitive substring filter over `files`; when no matches and `suggestNewFile`, pushes the raw query.

#### renderSuggestion(path, el)

```ts
renderSuggestion(path: string, el: HTMLElement)
```

Renders `path` with a trailing `.md` stripped.

#### onChooseSuggestion(_path, _evt)

```ts
onChooseSuggestion(_path: string, _evt: MouseEvent | KeyboardEvent)
```

Handles the selection event.

### Properties

#### promise

```ts
get promise(): Promise<TFile>
```

Resolves with the existing `TFile` via `vault.getAbstractFileByPath`. When the path doesn't exist and `suggestNewFile` is true, creates it (`FilepathHelper.extension(path) === undefined` → appends `.md`, then `vault.create(path, '')`) and resolves with the new `TFile`.
```

--------------------------------

### patch method signature

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/patcher.md

Core entry point for patching. Returns null when object is falsy. Selects target based on prototype flag. Throws error for missing methods when __overrideExisting is set. Applies patches via around() and registers uninstaller.

```typescript
static patch<T>(plugin: Plugin, object: T | undefined, patches: FunctionPatchObject<T>, prototype = false, uninstallers?: Array<() => void>): T | null
```

--------------------------------

### Patcher.waitForMapValueLookup

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/patcher.md

Wraps `map[viewType]` with `around(...)` so that the first time the view type is looked up, `patch(view)` runs on the returned view. Resolves with the patched view and uninstalls the wrapper.

```APIDOC
## Method: waitForMapValueLookup (protected, static)

### Description
Wraps `map[viewType]` with `around(...)` so that the first time the view type is looked up, `patch(view)` runs on the returned view. Resolves with the patched view and uninstalls the wrapper.

### Signature
```ts
protected static async waitForMapValueLookup<T>(map: Record<string, unknown>, viewType: string, patch: (view: T) => void): Promise<T>
```

### Parameters
- **map** (`Record<string, unknown>`) - Required - Registry map (e.g. `viewRegistry.viewByType`).
- **viewType** (`string`) - Required - The key to wait for (e.g. `'canvas'`, `'backlink'`, `'search'`, `'file-properties'`).
- **patch** (`(view: T) => void`) - Required - Runs once against the resolved view.

### Return
`Promise<T>` — the resolved (patched) view.
```

--------------------------------

### enableDebugMode()

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/advanced-canvas-plugin.md

Creates a DebugHelper if one does not already exist. Intended to be called externally via the plugin instance.

```APIDOC
## enableDebugMode()

### Description
Creates a DebugHelper if one does not already exist. Intended to be called externally via the plugin instance.

### Method
enableDebugMode

### Parameters
None

### Usage Example
this.app.plugins.plugins["advanced-canvas"].enableDebugMode()
```

--------------------------------

### createExpandablePopupMenuOption(menuOption, subMenuOptions)

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/canvas-helper.md

Creates an expandable popup menu option with sub-menu options.

```APIDOC
## createExpandablePopupMenuOption(menuOption, subMenuOptions)

### Description
Creates an expandable popup menu option with sub-menu options.

### Method
Static method

### Signature
```ts
static createExpandablePopupMenuOption(menuOption: MenuOption, subMenuOptions: MenuOption[]): HTMLElement
```

### Parameters
- **menuOption** (MenuOption) - Required - The main menu option configuration.
- **subMenuOptions** (MenuOption[]) - Required - Array of sub-menu options.

### Returns
- HTMLElement - The created expandable popup menu button element.
```

--------------------------------

### SettingsManager.getSetting(key)

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/settings-manager.md

Type-safe getter that returns the value stored under the given settings key.

```APIDOC
## getSetting(key)

### Description
Type-safe getter that returns the value stored under the given settings key.

### Method
getSetting

### Signature
`getSetting<T extends keyof AdvancedCanvasPluginSettingsValues>(key: T): AdvancedCanvasPluginSettingsValues[T]`

### Parameters
- **key** (`T extends keyof AdvancedCanvasPluginSettingsValues`) - Required - Any settings key. The return type is the property type of that key.

### Return Value
`AdvancedCanvasPluginSettingsValues[T]`

### Example
```ts
const value = settingsManager.getSetting('someKey');
```
```

--------------------------------

### parseStyleConfigsFromCSS() method signature

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/css-styles-config-manager.md

Splits the sheet's source text into YAML objects. Returns [] for empty sheets; malformed YAML is skipped.

```typescript
private parseStyleConfigsFromCSS(sheet: CSSStyleSheet): Record<string, unknown>[]
```

--------------------------------

### Patcher.waitForViewRequest

Source: https://github.com/developer-mike/obsidian-advanced-canvas/blob/main/_autodocs/api-reference/patcher.md

Convenience wrapper for waitForMapValueLookup that uses the plugin's view registry.

```APIDOC
## Method: waitForViewRequest (protected, static)

### Description
Convenience wrapper: `this.waitForMapValueLookup(plugin.app.viewRegistry.viewByType, viewType, patch)`.

### Signature
```ts
protected static async waitForViewRequest<T>(plugin: AdvancedCanvasPlugin, viewType: string, patch: (view: T) => void): Promise<T>
```

### Parameters
- **plugin** (`AdvancedCanvasPlugin`) - Required - The plugin instance.
- **viewType** (`string`) - Required - The key to wait for (e.g. `'canvas'`, `'backlink'`, `'search'`, `'file-properties'`).
- **patch** (`(view: T) => void`) - Required - Runs once against the resolved view.

### Return
`Promise<T>` — the resolved (patched) view.
```