docs(custom-nodes): add V3 backend docs into versioned /custom-nodes/v3 route (V1 kept, backward compatible)

custom-nodes/intro.mdx

@@ -22,6 +22,6 @@ Custom Nodes extend ComfyUI with new server-side behavior, user-interface featur
 ## Choose a starting point
 
 - **New to custom nodes:** start with [Custom Nodes Overview](/custom-nodes/overview).
-- **Building the backend:** see [Python (Backend)](/custom-nodes/backend/server_overview).
+- **Building the backend:** see [Python (Backend) · V3](/custom-nodes/v3/backend/server_overview). New nodes should use the V3 schema; find the [legacy V1 schema](/custom-nodes/backend/server_overview) in the V1 section.
 - **Extending the UI:** see [JavaScript (UI)](/custom-nodes/js/javascript_overview).
 - **Publishing a package:** start with the [Registry Overview](/registry/overview).

custom-nodes/overview.mdx

@@ -17,7 +17,7 @@
 - [ComfyUI-React-Extension-Template](https://github.com/Comfy-Org/ComfyUI-React-Extension-Template)
 - [ComfyUI_frontend_vue_basic](https://github.com/jtydhr88/ComfyUI_frontend_vue_basic)
 
 If you use Claude Code for development, the [ComfyUI Custom Node Skills](https://github.com/jtydhr88/comfyui-custom-node-skills) provide Claude with comprehensive knowledge of the ComfyUI node system, covering both the V3 and V1 APIs. Install it from the Claude Code marketplace or add the repository URL to get 9 skills covering node basics, inputs, outputs, datatypes, advanced patterns, frontend extensions, and packaging.
 
 
 
@@ -54,8 +54,8 @@
   <Card title="Getting Started" icon="play" href="/custom-nodes/walkthrough">
     Build and register a working custom node, step by step.
   </Card>
-  <Card title="Python (Backend)" icon="python" href="/custom-nodes/backend/server_overview">
-    The node class contract: properties, inputs, return types.
+  <Card title="Python (Backend) · V3" icon="python" href="/custom-nodes/v3/backend/server_overview">
+    The V3 node class contract: properties, inputs, return types.
   </Card>
   <Card title="JavaScript (UI)" icon="js" href="/custom-nodes/js/javascript_overview">
     Extend the ComfyUI frontend from your node package.

custom-nodes/v3/backend/datatypes.mdx

@@ -0,0 +1,214 @@
+---
+title: "ComfyUI Custom Node Datatypes (V3)"
+description: "Reference for ComfyUI custom node data types: Python types, tensor formats (IMAGE, LATENT, MASK), custom types, and wildcards for V3 custom nodes."
+---
+
+These are the most important built in datatypes. You can also [define your own](./more_on_inputs#custom-datatypes).
+
+In the V3 schema every datatype is a class in the `io` module, such as `io.Image` or `io.Int`. You declare
+an input with its `.Input(...)` constructor and an output with `.Output(...)`. See the
+[V3 Migration guide](/custom-nodes/v3_migration) for the full mapping between the V1 type strings and the
+`io` classes.
+
+Datatypes are used on the client side to prevent a workflow from passing the wrong form of data into a
+node - a bit like strong typing. The JavaScript client side code will generally not allow a node output to
+be connected to an input of a different datatype, although a few exceptions are noted below.
+
+## Comfy datatypes
+
+### COMBO
+
+`io.Combo` represents a dropdown menu widget. The value of the input is a `str`; the widget options are
+provided with the `options` parameter.
+
+```python
+io.Combo.Input("play_sound", options=["no", "yes"])
+```
+
+`COMBO` inputs are often dynamically generated at run time. Because `define_schema` is a class method, the
+options can be computed when the node is loaded. For instance, a checkpoint loader node might do:
+
+```python
+io.Combo.Input("ckpt_name", options=folder_paths.get_filename_list("checkpoints"))
+```
+
+There is also `io.MultiCombo` for dropdowns where more than one option can be selected; its value is a
+`list[str]`.
+
+### Primitive and reroute
+
+Primitive and reroute nodes only exist on the client side. They do not have an intrinsic datatype, but
+when connected they take on the datatype of the input or output to which they have been connected (which
+is why they can't connect to a `*` input...)
+
+## Python datatypes
+
+### INT
+
+`io.Int` is an integer widget input.
+
+* Parameters: `default`, `min`, `max`, `step` (all optional)
+
+* Python datatype: `int`
+
+```python
+io.Int.Input("count", default=1, min=0, max=4096, step=1)
+```
+
+### FLOAT
+
+`io.Float` is a float widget input.
+
+* Parameters: `default`, `min`, `max`, `step` (all optional)
+
+* Python datatype: `float`
+
+```python
+io.Float.Input("strength", default=1.0, min=0.0, max=10.0, step=0.1)
+```
+
+### STRING
+
+`io.String` is a text widget input.
+
+* Parameters: `default`, `multiline`, `placeholder`, `dynamic_prompts` (all optional)
+
+* Python datatype: `str`
+
+```python
+io.String.Input("text", default="Hello", multiline=True)
+```
+
+### BOOLEAN
+
+`io.Boolean` is a toggle widget input.
+
+* Parameters: `default`, `label_on`, `label_off` (all optional)
+
+* Python datatype: `bool`
+
+```python
+io.Boolean.Input("enabled", default=True, label_on="On", label_off="Off")
+```
+
+## Tensor datatypes
+
+### IMAGE
+
+* Declared with `io.Image.Input(...)`
+
+* Python datatype: `torch.Tensor` with *shape* \[B,H,W,C]
+
+A batch of `B` images, height `H`, width `W`, with `C` channels (generally `C=3` for `RGB`).
+
+### LATENT
+
+* Declared with `io.Latent.Input(...)`
+
+* Python datatype: `dict`, containing a `torch.Tensor` with *shape* \[B,C,H,W]
+
+The `dict` passed contains the key `samples`, which is a `torch.Tensor` with *shape* \[B,C,H,W] representing
+a batch of `B` latents, with `C` channels (generally `C=4` for existing stable diffusion models), height `H`, width `W`.
+
+The height and width are 1/8 of the corresponding image size (which is the value you set in the Empty Latent Image node).
+
+Other entries in the dictionary contain things like latent masks.
+
+{/* TODO need to dig into this */}
+
+{/* TODO new SD models might have different C values? */}
+
+### MASK
+
+* Declared with `io.Mask.Input(...)`
+
+* Python datatype: `torch.Tensor` with *shape* \[H,W] or \[B,C,H,W]
+
+### AUDIO
+
+* Declared with `io.Audio.Input(...)`
+
+* Python datatype: `dict`, containing a `torch.Tensor` with *shape* \[B, C, T] and a sample rate.
+
+The `dict` passed contains the key `waveform`, which is a `torch.Tensor` with *shape* \[B, C, T] representing a batch of `B` audio samples, with `C` channels (`C=2` for stereo and `C=1` for mono), and `T` time steps (i.e., the number of audio samples).
+
+The `dict` contains another key `sample_rate`, which indicates the sampling rate of the audio.
+
+## Custom Sampling datatypes
+
+### Noise
+
+The `NOISE` datatype represents a *source* of noise (not the actual noise itself). It can be represented by any Python object
+that provides a method to generate noise, with the signature `generate_noise(self, input_latent:Tensor) -> Tensor`, and a
+property, `seed:Optional[int]`.
+
+<Tip>The `seed` is passed into `sample` guider in the `SamplerCustomAdvanced`, but does not appear to be used in any of the standard guiders.
+It is Optional, so you can generally set it to None.</Tip>
+
+When noise is to be added, the latent is passed into this method, which should return a `Tensor` of the same shape containing the noise.
+
+See the [noise mixing example](/custom-nodes/backend/snippets#creating-noise-variations)
+
+### Sampler
+
+The `SAMPLER` datatype represents a sampler, which is represented as a Python object providing a `sample` method.
+Stable diffusion sampling is beyond the scope of this guide; see `comfy/samplers.py` if you want to dig into this part of the code.
+
+### Sigmas
+
+The `SIGMAS` datatypes represents the values of sigma before and after each step in the sampling process, as produced by a scheduler.
+This is represented as a one-dimensional tensor, of length `steps+1`, where each element represents the noise expected to be present
+before the corresponding step, with the final value representing the noise present after the final step.
+
+A `normal` scheduler, with 20 steps and denoise of 1, for an SDXL model, produces:
+
+```
+tensor([14.6146, 10.7468,  8.0815,  6.2049,  4.8557,  
+         3.8654,  3.1238,  2.5572,  2.1157,  1.7648,  
+         1.4806,  1.2458,  1.0481,  0.8784,  0.7297,  
+         0.5964,  0.4736,  0.3555,  0.2322,  0.0292,  0.0000])
+```
+
+<Tip>The starting value of sigma depends on the model, which is why a scheduler node requires a `MODEL` input to produce a SIGMAS output</Tip>
+
+### Guider
+
+A `GUIDER` is a generalisation of the denoising process, as 'guided' by a prompt or any other form of conditioning. In Comfy the guider is
+represented by a `callable` Python object providing a `__call__(*args, **kwargs)` method which is called by the sample.
+
+The `__call__` method takes (in `args[0]`) a batch of noisy latents (tensor `[B,C,H,W]`), and returns a prediction of the noise (a tensor of the same shape).
+
+## Model datatypes
+
+There are a number of more technical datatypes for stable diffusion models. The most significant ones are `io.Model`, `io.CLIP`,
+`io.VAE` and `io.Conditioning`.
+Working with these is (for the time being) beyond the scope of this guide! {/* TODO but maybe not forever */}
+
+## Additional Parameters
+
+The `Input` constructors of the widget datatypes accept a number of optional parameters that configure the
+widget. Below is a list of the officially supported parameters. (The legacy V1 schema spelled these as keys
+in the input options dictionary, e.g. `forceInput` and `rawLink`; in V3 they are snake_case parameters of
+the `Input` constructors.)
+
+<Warning>You can use additional keys for your own custom widgets, but should *not* reuse any of the parameters below for other purposes.</Warning>
+
+| Parameter             | Applies to                | Description                                                                                                                   |
+| --------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `default`             | widget inputs             | The default value of the widget                                                                                               |
+| `min`                 | `io.Int`, `io.Float`      | The minimum value of the widget                                                                                               |
+| `max`                 | `io.Int`, `io.Float`      | The maximum value of the widget                                                                                               |
+| `step`                | `io.Int`, `io.Float`      | The amount to increment or decrement a widget                                                                                  |
+| `multiline`           | `io.String`               | Use a multiline text box                                                                                                      |
+| `placeholder`         | `io.String`               | Placeholder text to display in the UI when empty                                                                               |
+| `dynamic_prompts`     | `io.String`               | Causes the front-end to evaluate dynamic prompts                                                                               |
+| `options`             | `io.Combo`, `io.MultiCombo` | The dropdown options                                                                                                        |
+| `label_on`, `label_off` | `io.Boolean`            | The labels to use in the UI when the bool is `True` / `False`                                                                  |
+| `control_after_generate` | `io.Int`, `io.Combo`    | Adds a "control after generate" widget (pass `True`, or an `io.ControlAfterGenerate` enum value)                              |
+| `socketless`          | widget inputs             | Hide the input socket, so the widget cannot be connected to an upstream node                                                   |
+| `force_input`         | widget inputs             | Display the input as a socket instead of a widget, and don't allow converting it back to a widget                              |
+| `optional`            | all inputs                | Declares the input optional, so it does not have to be connected                                                               |
+| `lazy`                | all inputs                | Declares that this input uses [Lazy Evaluation](./lazy_evaluation)                                                            |
+| `raw_link`            | all inputs                | When a link exists, rather than receiving the evaluated value, you will receive the link (i.e. `["nodeId", <outputIndex>]`). Primarily useful when your node uses [Node Expansion](/custom-nodes/backend/expansion). |
+| `tooltip`             | all inputs                | Tooltip text to display when hovering over the input                                                                           |
+| `advanced`            | all inputs                | Hides the input behind an "Advanced" toggle in the UI                                                                          |