> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-docs-custom-nodes-sdk-v2-frontend.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning and capabilities

> Track the frontend contract, probe optional behavior, and declare hard dependencies.

A pack selects a filesystem version, and the JavaScript API then reports its own contract version and capability grants.

## Pack filesystem versions

The pack's filesystem version is selected before either language API loads. A converted pack retains its complete V1 distribution at the pack root and stores its complete replacement V2 distribution under `v2/`.

```text theme={null}
my_pack/
├── <V1 files and folders>
└── v2/
    └── <V2 files and folders in the same relative layout>
```

The `v2/` directory is a replacement pack root, not a patch or overlay and not the Python API module name. It is generally copied from the top-level distribution before conversion. When selected, frontend modules inside it import `/comfy/api/v2.js`. Keep version-specific entrypoints, dependencies, assets, and metadata inside their respective distribution trees; do not rely on fallback to V1.

## JavaScript versions

Import the published module directly:

```javascript theme={null}
import { comfy } from '/comfy/api/v2.js'
```

`comfy.version` reports the contract as `major.minor`. A major change can remove behavior. A minor change only adds behavior. `comfy.forMajor(major)` keeps a pack on a supported major during a deprecation period.

Do not branch on a version string when you need one feature. Backports and grant policy can make a version comparison inaccurate.

## Probe a capability

```javascript theme={null}
if (comfy.supports('slots.connectedType')) {
  installTypedConnectionBehavior()
}
```

`supports()` is cheap and does not throw. Its answer includes both host support and the current pack grant.

Use `require()` when the extension has no useful behavior without the feature:

```javascript theme={null}
comfy.require('defs.extend')
```

Use `comfy.capabilities()` for diagnostics or a compatibility report, not to request everything the host offers.

<Warning>
  Capability discovery does not grant authority. A pack should declare the narrow set it needs and continue without optional enhancements when possible.
</Warning>

## Request a missing capability

The V2 API is intended to grow with real node-author needs. If a useful node cannot be implemented through the published surface, report the missing operation or extension point instead of building a permanent dependency on private ComfyUI internals.

A useful capability request includes:

* the user-visible behavior the node is trying to provide;
* the old API, private object, or monkeypatch currently used;
* why existing refs, context services, handles, hooks, or UI contributions are insufficient;
* whether the capability is required or an optional enhancement;
* a small example showing the desired author-facing API when practical.

New capabilities should express the useful outcome without exposing unrelated application internals. Until one is available, keep the workaround clearly optional so the main V2 behavior does not depend on a private implementation detail.

## Handle API generations

Two handles can describe the same entity while coming from different API instances, graph scopes, or majors. Compare them with `comfy.sameEntity()`:

```javascript theme={null}
if (comfy.sameEntity(current, event.node)) {
  updateStatus()
}
```

Use `comfy.adopt(handle)` to re-resolve a node handle into the current API instance. It returns `undefined` when the value is not a node handle or the entity is gone.

## Compatibility policy for a pack

1. Import `/comfy/api/v2.js` and require only hard dependencies.
2. Probe optional enhancements individually with `supports()`.
3. Keep a released pack on a supported major with `comfy.forMajor()`.
4. Treat an ungranted capability as unavailable rather than reaching for a private equivalent.
5. Never fall back to a private import, global object, path, or DOM selector.
6. Report a named API gap and its user-visible use case when the supported surface cannot express required behavior.