diff --git a/README.md b/README.md index 9dc5e30..e61c4aa 100644 --- a/README.md +++ b/README.md @@ -1,55 +1,42 @@ -# BV Node Pack (ComfyUI) +# BV Node Pack for ComfyUI -A curated collection of **quality-of-life**, **UI**, and **prompting** nodes for **ComfyUI**, with a strong focus on: +![BV Node Pack hero](docs/assets/bv-nodepack-hero.svg) -- clean graph layouts -- Subgraph/Subflow compatibility -- metadata-driven pipelines -- AST-based prompt tooling (no fragile string parsing) +BV Node Pack is a collection of deep workflow tools for **regional prompting**, +**structured prompts**, **Smart Pipes**, **Subgraph interfaces**, reusable graph +controls and deterministic latent utilities. -> ⚠️ **Important** -> This pack includes **JavaScript UI extensions** for dynamic node behavior. -> These extensions fully support **Subgraphs / Subflows**. +The pack targets current ComfyUI workflows and treats stable data contracts, +Subgraph behavior and graceful failure as first-class features. ---- +> BV Node Pack includes frontend extensions. Restart ComfyUI and hard-refresh the +> browser after installing or updating so Python nodes and JavaScript stay in sync. -## πŸ“Œ Table of Contents +## Highlights -- [Installation](#installation) -- [Update & Uninstall](#update--uninstall) -- [Node Overview](#node-overview) - - [Example Workflows](#example-workflows) - - [Pipe Nodes](#pipe-nodes) - - [UI / Layout Nodes](#ui--layout-nodes) - - [Prompt / AST Nodes](#prompt--ast-nodes) - - [Regional Prompting Nodes](#regional-prompting-nodes) - - [Latent Nodes](#latent-nodes) - - [Util Nodes](#util-nodes) - - [Control Nodes](#control-nodes) -- [Prompt AST Syntax & Markup Guide](#prompt-ast-syntax--markup-guide) -- [Example application for AST](#example-application-for-ast) -- [Quick Start (BV Smart Pipe)](#quick-start-bv-smart-pipe) -- [Notes & Design Principles](#notes--design-principles) -- [Changelog](#changelog) - ---- +| Feature | What it solves | +| --- | --- | +| [Regional Editor](#regional-prompting) | Author any number of named, overlapping rectangle and brush regions in a floating or workspace editor | +| [Prompt Autocomplete](#prompt-autocomplete) | Local, optional CSV/TSV completion in BV editors and ordinary ComfyUI multiline fields | +| [Prompt AST](#structured-prompt-ast) | Filter and reuse semantic prompt blocks without fragile string replacement | +| [Smart Pipe](#smart-pipes) | Grow typed workflow state through wired or wireless branches while retaining stable slot identity | +| [Subgraph UI](#subgraph-interface-nodes) | Project headings, dividers, spacers and controlled choices onto purpose-built Subgraphs | +| [Control Center](#workflow-control) | Switch named graph stages between activate, mute and bypass with deterministic conflict handling | ## Installation -Clone into your ComfyUI `custom_nodes` folder: +### ComfyUI Manager + +Search for **BV Node Pack** in the Custom Nodes Manager / Extensions view and install it. + +### Git ```bash cd ComfyUI/custom_nodes git clone https://github.com/BlackVortexAI/bv_nodepack.git ``` -Restart ComfyUI and hard-refresh the browser: - -**Ctrl + F5** - ---- - -## Update & Uninstall +Restart ComfyUI, then hard-refresh the browser with **Ctrl + F5**. ### Update @@ -58,681 +45,446 @@ cd ComfyUI/custom_nodes/bv_nodepack git pull ``` -Restart ComfyUI (recommended). +Restart ComfyUI after updates. To uninstall, remove the `bv_nodepack` directory, +restart ComfyUI and hard-refresh the browser. -### Uninstall +## Regional prompting -1. Delete the folder in `custom_nodes` -2. Restart ComfyUI -3. Hard refresh the browser (**Ctrl + F5**) +The model-neutral `BV_REGIONAL` document separates authoring from execution. The +editor stores prompts, geometry and stable identities; compiler nodes translate +that document for a particular model/backend. ---- +[![Anima regional prompting result](examples/images/anima-android-dance-regional-showcase.png)](examples/images/anima-android-dance-regional-showcase.png) -## Node Overview +This Anima example uses two independently conditioned androids, small overlapping +interaction rectangles around their hands and a painted light-arc region. The +character prompts do not encode left/right placement; the regional document supplies +the spatial guidance. -Nodes are grouped by **functional category**. -Each section below can be read independently. +[Download the workflow PNG](examples/images/anima-android-dance-regional-showcase.png) +Β· [Download the regional document](docs/examples/anima-android-dance-regional-showcase.bv-regional.json) ---- +> [!IMPORTANT] +> Regional conditioning is spatial guidance, not a hard segmentation or layout +> constraint. A model can extend subjects beyond a region, move an interaction, +> blend attributes or ignore part of the requested composition. `joint` overlap +> lets overlapping pixels attend to multiple regional contexts; it does not force +> the depicted subjects to interact. Region strength changes conditioning influence, +> not boundary strictness. -## Example Workflows +### Core workflow -Each preview is also an importable ComfyUI workflow: download the PNG and drag it onto the canvas. The matching JSON is provided as a metadata-independent fallback. +1. Add **BV Regional Prompt** and open it from the node or BV toolbar action. +2. Define Global and Background prompts. +3. Add regions, then draw rectangles or additive/subtractive brush layers. +4. Connect `regional` to a compiler: + - **BV Regional Native Conditioning** for standard masked ComfyUI conditioning; + - **BV Regional Anima Conditioning** for the built-in Anima attention backend. +5. Connect `patched_model`/`positive`/`negative` to a standard KSampler. +6. Optionally return the latest image through **Preview Send** or **Save Send**. -
-Smart Pipe: wireless branches and ordered merge +The editor supports overlap, priority ordering, undo/redo, layer controls, zoom, +pan, WYSIWYG aspect ratios, document import/export and persistent per-document UI state. -[![Smart Pipe wireless merge example](examples/images/smart-pipe-wireless-merge.png)](examples/images/smart-pipe-wireless-merge.png) +Read the illustrated **[Regional Editor Guide](docs/regional-editor-guide.md)** for +tools, prompts, model behavior, image feedback, document utilities and current limits. -Two independently populated pipes are merged wirelessly and then inherited by the next processing stage. [Workflow JSON](examples/workflows/smart-pipe-wireless-merge.json) +
+Open the editor and use Quick Edit + +The node exposes both entry points directly: + +![BV Regional Prompt node](docs/assets/regional/regional-prompt-node.png) + +The same actions are available from the ComfyUI toolbar for the currently selected +regional document: + +![BV toolbar actions](docs/assets/regional/toolbar-actions.png) + +![Open editor toolbar action](docs/assets/regional/toolbar-editor-hover.png) + +![Quick Edit toolbar action](docs/assets/regional/toolbar-quick-hover.png) + +Quick Edit provides prompt-only access without opening the artboard: + +![Regional Quick Edit](docs/assets/regional/quick-edit.png)
-Control Center: reusable workflow states +Workspace, floating mode and display controls -[![Control Center workflow-state example](examples/images/control-center-workflow-states.png)](examples/images/control-center-workflow-states.png) +![Regional Editor workspace mode](docs/assets/regional/editor-workspace.png) -Multiple synchronized Control Center nodes manage grouped generation stages while showing their active state and conflict status directly on the graph. [Workflow JSON](examples/workflows/control-center-workflow-states.json) +![Regional Editor floating mode](docs/assets/regional/editor-floating.png) + +Mask visibility and background-image opacity are editor-only display settings: + +![Regional Editor display controls](docs/assets/regional/view-controls.png)
-Subgraph UI: heading, combo, divider and spacer +Rectangles, interaction overlap and brush regions -[![Subgraph UI layout example](examples/images/subgraph-ui-layout.png)](examples/images/subgraph-ui-layout.png) +Each character uses a main rectangle plus an independently selectable interaction +rectangle. The brush region demonstrates a non-rectangular light arc. -The presentation nodes are arranged in the logical order in which they should be exposed on a purpose-built Subgraph interface. [Workflow JSON](examples/workflows/subgraph-ui-layout.json) +![Cyan character main region](docs/assets/regional/region-cyan-main.png) + +![Cyan interaction region](docs/assets/regional/region-cyan-interaction.png) + +![Amber character main region](docs/assets/regional/region-amber-main.png) + +![Amber interaction region](docs/assets/regional/region-amber-interaction.png) + +![Painted light arc region](docs/assets/regional/region-brush-arc.png)
-Random-ratio latent for composition exploration +Minimal Anima workflow -[![Random-ratio latent example](examples/images/empty-latent-random-ratio.png)](examples/images/empty-latent-random-ratio.png) +![Anima regional workflow](docs/assets/regional/anima-workflow.png) -A deterministic mix of common and project-specific aspect ratios feeds a sampler while width, height and ratio remain available for metadata and post-processing. [Workflow JSON](examples/workflows/empty-latent-random-ratio.json) +
+ +### Regional node family + +| Node | Purpose | +| --- | --- | +| BV Regional Prompt | Owns and outputs the serialized `BV_REGIONAL` document | +| BV Regional Native Conditioning | Compiles Global, Background and region masks into standard conditioning | +| BV Regional Anima Conditioning | Applies the built-in Anima attention patch and emits KSampler-ready outputs | +| BV Regional Anima Adapter | Optional compatibility path for the external Anima regional node pack | +| BV Regional Preview Send | Sends a temporary image preview to a selected editor | +| BV Regional Save Send | Saves and sends the same image to a selected editor | +| BV Regional Debug | Shows canonical JSON, a summary and `document_id` | +| BV Regional Select | Selects Global, Background or one region | +| BV Regional Deconstructor | Exposes AST, text, source and reusable selection data | +| BV Regional Prompt Extract | Extracts positive/negative prompt representations | +| BV Regional Mask Render | Renders a selected mask and pixel bounding box | + +## Prompt autocomplete + +BV Prompt Autocomplete uses local datasets and does not require another completion +extension. The bundled `data/completion/bv_default_tags.csv` is active by default. + +- Supports legacy four-column CSV and extensible header-based CSV/TSV files. +- Preserves descriptions, provenance, safety scores and unknown future metadata. +- Inserts tag names with spaces while retaining canonical underscore tags as metadata. +- Works in the Regional Editor, Quick Edit and ordinary ComfyUI multiline widgets. +- Can be disabled globally or inside the editor when another completer should own fields. +- Supports multiple ordered datasets; the topmost enabled source wins duplicate tags. + +Custom widgets can opt out with `data-bv-autocomplete="off"` on the textarea or an ancestor. +An absolute dataset may be forced with the `BV_COMPLETION_DATASET` environment variable. + +
+Autocomplete in Quick Edit, the full editor and native multiline widgets + +![Autocomplete in Quick Edit](docs/assets/regional/autocomplete-quick-edit.png) + +![Autocomplete in the full Regional Editor](docs/assets/regional/autocomplete-editor.png) + +![Autocomplete in a native multiline widget](docs/assets/regional/autocomplete-multiline.png)
-Prompt AST: category-based prompt variants +Dataset selection, priority and global enable switch -[![Prompt AST category example](examples/images/prompt-ast-categories.png)](examples/images/prompt-ast-categories.png) - -One structured prompt is filtered into a generation variant while the complete AST remains inspectable during workflow construction. [Workflow JSON](examples/workflows/prompt-ast-categories.json) +![BV Prompt Autocomplete settings](docs/assets/regional/completion-settings.png)
---- +## Smart Pipes -## Pipe Nodes +**BV Smart Pipe** carries a chain-growing set of values identified by stable slot +IDs. Each node exposes only the inputs and outputs required at that point in the workflow. + +### Incremental slot inheritance + +Unlike fixed pipe systems, a Smart Pipe does not expose one global port list on +every node. Each node inherits the complete slot contract of its selected predecessor +and may append new slots locally. Those additions become available only from that +point downstream; they do not appear retroactively on earlier nodes or unrelated branches. + +| Chain position | Visible contract | +| --- | --- | +| Loader pipe | Local `model`, `clip`, `vae` | +| Prompt pipe | Inherited `model`, `clip`, `vae` + local `positive`, `negative` | +| Sampling pipe | Everything inherited above + local `latent`, `seed` | + +Inherited slots can be passed through unchanged or overridden at the current node. +Because every slot has a stable logical identity, downstream connections continue to +refer to the correct value even when labels change or an upstream slot is temporarily missing. + +[![Smart Pipe wireless merge](examples/images/smart-pipe-wireless-merge.png)](examples/images/smart-pipe-wireless-merge.png) + +- Wired and wireless routing can be mixed. +- Each branch inherits only its own upstream slots and can grow independently. +- Bypassed nodes pass inherited state without applying local writes. +- Muted nodes stop only their dependent execution branch. +- Removed upstream slots remain identifiable instead of silently shifting connections. +- **BV Smart Pipe Merge** combines branches in explicit user-defined order. +- Missing sources and cycles fail closed. + +Configure slots through **Configure Smart Pipe**. The legacy **BV Pipe Config** and +**BV Pipe** nodes remain available only for existing workflows. + +> Wireless routing across Subgraph boundaries relies on prompt materialization because +> ComfyUI does not currently expose an official pre-prompt extension hook. Keep physical +> pipe links in compatibility-critical workflows. + +## Structured Prompt AST + +Prompt AST nodes preserve semantic categories instead of repeatedly parsing flattened text. + +[![Prompt AST categories](examples/images/prompt-ast-categories.png)](examples/images/prompt-ast-categories.png) + +| Node | Purpose | +| --- | --- | +| BV Prompt Encode | Parses tagged source into `BV_AST` plus cleaned text | +| BV Prompt Category Switch | Enables/disables categories with inheritance and any/all matching | +| BV Prompt Decode | Materializes selected categories as plain text | +| BV Prompt AST Debug | Displays the current AST as formatted JSON | + +See the **[Prompt AST syntax and markup guide](docs/prompt-ast-guide.md)**. + +## Subgraph interface nodes + +These nodes build readable, purpose-specific Subgraph surfaces instead of exposing +an undifferentiated list of widgets. + +[![Subgraph UI layout](examples/images/subgraph-ui-layout.png)](examples/images/subgraph-ui-layout.png) + +| Node | Purpose | +| --- | --- | +| BV Subgraph Heading | A projected section title with optional divider | +| BV Subgraph Divider | A projected visual separator | +| BV Subgraph Spacer | Controlled vertical spacing | +| BV Dynamic Combo | A controlled choice that also emits string, integer and float views | + +Presentation identity and serialized port identity remain separate so reload, +copying and nested Subgraphs do not reorder exposed controls. + +To project one of these presentation nodes onto a Subgraph interface: + +1. Create or open the Subgraph and add the presentation node between the controls + it should visually separate. +2. Expose the node's left input as a Subgraph input. +3. Wire the surrounding data inputs to preserve the intended interface order. +4. Return to the parent graph. The exposed input is rendered as the heading, + divider or spacer instead of an ordinary editable field.
-BV Smart Pipe +Heading: internal wiring and resulting Subgraph -A chain-growing pipe with stable slot identities and per-node projections. +The heading input is exposed between the controls that should appear above and below it. -**What it does** -- Opens its schema editor through the Configure button or context menu -- Adds up to 100 local slots and inherits upstream slots -- Allows each node to expose only the inputs and outputs needed at that point -- Keeps branches independent and transports all values through the pipe connection -- Passes inherited values across bypassed Smart Pipe nodes without applying their local writes -- Treats a muted Smart Pipe as a temporary execution-branch stop without changing the saved workflow -- Omits muted Merge sources for the current run; a Merge with no active sources stops only its dependent branch -- Marks slots from a removed upstream producer as missing instead of shifting links -- Blocks execution when a missing slot is still connected +![Heading wired inside a Subgraph](docs/screenshots/bv_subgraph_heading_in_subgraph.png) -Slot types start as `*` and are persisted after inference from the first connection. +The parent Subgraph node renders that exposed position as a heading: -**Configure local slots** +![Heading rendered on a Subgraph](docs/screenshots/bv_subgraph_heading_subgraph.png) -![Smart Pipe slot configuration](examples/images/smart-pipe-slot-config.png) +The heading text, font size and optional divider remain configurable on the inner node: -1. Add one or several local slot names. -2. Connect each local input so its type can be inferred and persisted. -3. Enable outputs only where a downstream node actually consumes the value. - -> **Experimental:** Wireless routing, especially across Subgraph boundaries, depends on a prompt-materialization adapter because ComfyUI does not yet expose an official pre-prompt extension hook. Keep physical Pipe links for compatibility-critical workflows until the Nodes 2.0, partial-execution and third-party wrapper matrix has been completed. +![Editing a Subgraph heading](docs/screenshots/bv_subgraph_heading_edit.png)
-BV Smart Pipe Merge +Divider: internal wiring and resulting Subgraph -Combines several Smart Pipe branches in an explicit, user-defined order. +![Divider wired inside a Subgraph](docs/screenshots/bv_divider_in_subgraph.png) -**What it does** -- Mixes wired and wireless Smart Pipe sources -- Adds wired sources through the temporary `Add Pipe Source` connector -- Adds wireless sources through the configuration dialog -- Prevents the same source from being selected more than once -- Keeps different stable slot IDs separate even when their visible names match -- Preserves a genuine branch write when a later source only inherited the shared base value -- Lets the later source win when several branches genuinely changed the same stable slot ID -- Exposes the merged Pipe Schema to subsequent Smart Pipe nodes -- Rejects missing sources and cycles instead of silently producing incomplete data - -**Configure source order** - -![Smart Pipe Merge configuration](examples/images/smart-pipe-merge-config.png) - -Wireless and wired sources share the same ordered list. For colliding stable Slot IDs, the later genuine branch write wins. +![Divider rendered on a Subgraph](docs/screenshots/bv_divider_subgraph.png)
-BV Pipe Config [Deprecated] +Spacer: internal wiring and resulting Subgraph -Defines the slot layout (names) for a BV Pipe. +![Spacer wired inside a Subgraph](docs/screenshots/bv_spacer_in_subgraph.png) -**Screenshot** -> Shows the BV Pipe Config node with a multiline list of slot names. -> -> ![BV Pipe Config](docs/screenshots/bv_pipe_config.png) - -**What it does** -- Define slot names (1 per line, max 100) -- Outputs a single `BV_PIPE` object (the "pipe") - -**How to use** -1. Add **BV Pipe Config** -2. Enter slot names (one per line) -3. Connect its `pipe` output to **BV Pipe** +![Spacer rendered on a Subgraph](docs/screenshots/bv_spacer_subgraph.png)
+## Workflow control + +**BV Control Center** defines named workflow states and applies explicit +`Activate`, `Mute` or `Bypass` actions to graph/Subgraph groups. + +[![Control Center workflow states](examples/images/control-center-workflow-states.png)](examples/images/control-center-workflow-states.png) + +- Multiple Control Center nodes remain synchronized. +- Groups are discovered recursively in the root graph and inside Subgraphs, + including nested Subgraphs, and are shown with their qualified Subgraph path. +- `Mute` and `Bypass` are applied to the nodes contained in the selected group, + even when that group lives inside a Subgraph definition. +- A group belongs to its reusable Subgraph definition. If that definition has + several instances, its controlled node modes therefore apply to every instance. +- Active conflicts resolve deterministically as `Activate > Mute > Bypass`. +- Conflicts and unresolved groups remain visible and block unsafe execution. +- Base node modes are restored when controls stop applying. +
-BV Pipe [Deprecated] +Configure workflow states and group actions -A config-driven carrier node that forwards one pipe connection while exposing named slots. +Each named state can assign `Activate`, `Mute` or `Bypass` to any discovered root +or Subgraph group. -**Screenshots** -> Connected state (slots visible) -> -> ![BV Pipe Connected](docs/screenshots/bv_pipe_connected.png) - -> Slot override example -> -> ![BV Pipe Override](docs/screenshots/bv_pipe_override.png) - -> Subgraph usage -> -> ![BV Pipe Subgraph](docs/screenshots/bv_pipe_subgraph.png) - -**What it does** -- Shows only the slots defined by the connected **BV Pipe Config** -- Allows overriding individual slots -- Passes through all untouched slots +![Control Center configuration](examples/images/control-center-config.png)
---- - -## UI / Layout Nodes - -
-BV Subgraph Heading - -A UI node that renders a bold header text inside the node. - -Designed specifically for **Subgraphs/Subflows**: -When exposed, the heading is also rendered on the Subgraph node itself. - -**Screenshots** -> Heading inside normal graph -> -> ![BV Subgraph Heading](docs/screenshots/bv_subgraph_heading.png) - -> Heading inside Subgraph -> -> ![BV Subgraph Heading Subgraph](docs/screenshots/bv_subgraph_heading_in_subgraph.png) - -> Heading rendered on Subgraph node -> -> ![BV Subgraph Heading](docs/screenshots/bv_subgraph_heading_subgraph.png) - -> Editing the heading text (click on header text to edit) -> -> ![BV Subgraph Heading Edit](docs/screenshots/bv_subgraph_heading_edit.png) - -**Inputs** -- `value` (STRING) β€” header text -- `font_size` (INT) β€” font size -- `show_divider` (BOOLEAN) β€” optional divider - -
- -
-BV Spacer - -A UI-only spacer node used to add vertical whitespace. - -**Screenshots** -> Normal graph -> -> ![BV Spacer](docs/screenshots/bv_spacer.png) - -> Inside Subgraph -> -> ![BV Spacer Subgraph](docs/screenshots/bv_spacer_in_subgraph.png) - -> Subgraph node view -> -> ![BV Spacer Subgraph](docs/screenshots/bv_spacer_subgraph.png) - -> Editing the spacer height (click on spacer to edit) -> -> ![BV Spacer Edit](docs/screenshots/bv_spacer_edit.png) - -**Inputs** -- `height` (INT) β€” spacer height in pixels -- `scale` (FLOAT, optional) β€” multiplier - -
- -
-BV Divider - -A UI-only divider node that draws a horizontal separator line. - -**Screenshots** -> Divider in graph -> -> ![BV Divider](docs/screenshots/bv_divider.png) - -> Divider inside Subgraph -> -> ![BV Divider Subgraph](docs/screenshots/bv_divider_in_subgraph.png) - -> Divider rendered on Subgraph node -> -> ![BV Divider Subgraph](docs/screenshots/bv_divider_subgraph.png) - -**Inputs** -- `thickness` (INT) -- `padding` (INT) -- `alpha` (FLOAT) - -
-
-BV Dynamic Combo - -**Purpose** -- Creates a dynamic combo box from a list of strings - -**Input** -- `prompt` (COMBO, STRING) - -**Output** -- `value_str` (`STRING`) -- `value_int` (`INT`) -- `value_float` (`FLOAT`) -
- ---- - -## Prompt / AST Nodes - -> These nodes operate on a **structured AST (Abstract Syntax Tree)**, not on raw strings. -> This allows safe filtering, switching, inspection, and refactoring of prompts. - -
-BV Prompt Encode - -**Purpose** -- Parses a tagged prompt into an AST - -**Input** -- `prompt` (STRING, multiline) - -**Output** -- `ast` (`BV_AST`) -- `cleaned_prompt` (plain text, no markup, no comments) - -Comment text is removed while its line break is preserved. - -**Screenshot** -> Example output -> -> ![BV Prompt Encode](docs/screenshots/bv_prompt_encoder.png) - -
- -
-BV Prompt Decode - -**Purpose** -- Extracts plain text from the AST by category - -**Key Features** -- Multi-category filtering -- `any` / `all` matching -- Inheritance (parent categories) -- Optional prettify pass -- If no filter is set, all categories are displayed. - -**Screenshot** -> Example output -> -> ![BV Prompt Decode](docs/screenshots/bv_prompt_decoder.png) - -
- -
-BV Prompt AST Debug - -**Purpose** -- Visual inspection of the AST - -**Features** -- JSON pretty-print -- Readonly, scrollable output field -- Safe for large ASTs - -**Screenshot** -> Example output -> -> ![BV Prompt AST Debug](docs/screenshots/bv_prompt_ast_debug.png) - -
- -
-BV Prompt Category Switch - -**Purpose** -- Enable / disable categories directly on the AST -- No string parsing - -**Features** -- Enable categories -- Disable categories (wins over enable) -- `inherit` and `any/all` matching - -**Screenshot** -> Example output -> -> ![BV Prompt Category Switch](docs/screenshots/bv_prompt_switch.png) - -
- ---- - -## Prompt AST Syntax & Markup Guide - -This section explains the **exact prompt syntax** that is parsed into the AST. - -### Default (no markup) -```text -A beautiful landscape, sunset lighting -``` - -### Block categories -```text -@@style -cinematic lighting -@@subject -a woman in rain -``` - -### Inline categories -```text -a portrait with @ green eyes @@ and @ black hair @@ -``` - -### Nested inline categories -```text -@ a @ smiling woman @@ in rain @@ -``` - -### Comments -```text -a portrait ## this is a comment -``` - -### ⚠️ Common Syntax Pitfalls (Important) - -Category names must not contain spaces. - -Inline categories are only recognized if the category name matches this pattern: - ->[a-zA-Z0-9_-]+ - - -#### ❌ Invalid -```text -@ white dress @@ -``` - -βœ… Valid -```text -@ white dress @@ -``` -### Closing inline categories (@@) -```text -@@ closes one currently open inline category -``` - -Every inline category must be closed. An unmatched `@@` or an unclosed inline -category raises an error with its line and column. -### ❌ Invalid (too many closings) -```text -@ long dress,@@@@ -``` - -βœ… Valid -```text -@ long dress,@@ -``` - -## Example application for AST -![BV AST Example](workflows/workflow_AST_with_pipe.png) ---- - -## Regional Prompting Nodes - -The Regional toolset stores prompts and editable geometry in the model-neutral -`BV_REGIONAL` document format. The editor supports any number of named regions, -rectangles and brush layers, overlapping masks, priorities, undo/redo, quick -prompt editing, floating/workspace modes, and an optional background image. - -**Core workflow** - -1. Create a **BV Regional Prompt** node and open the editor from the node or toolbar. -2. Define the Global and Background prompts, then add and paint the required regions. -3. Connect the `regional` output to a model-specific compiler: - - **BV Regional Native Conditioning** produces standard masked ComfyUI conditioning. - - **BV Regional Anima Conditioning** applies the built-in Anima attention patch and works with a standard KSampler. -4. Optionally use **BV Regional Preview Send** or **BV Regional Save Send** to send the latest generated image back to a selected editor. If several senders execute, the last completed sender wins. - -The editor document can also be inspected and reused through **Debug**, **Select**, -**Deconstructor**, **Prompt Extract**, and **Mask Render** nodes. The legacy -**Anima Adapter** remains available for workflows that intentionally use the -external Anima regional-conditioning package. - -Prompt fields in the full editor and Quick Edit use the optional BV Local Tags -provider. It supports legacy four-column CSV data as well as extensible CSV/TSV -files with descriptions, provenance and future custom metadata. Put a dataset at -`data/completion/`. The bundled `bv_default_tags.csv` is selected by default, so no other custom-node package -is required. `BV_COMPLETION_DATASET` may override it with an absolute CSV/TSV path. -Dataset loading is lazy and cannot prevent the editor from opening. -Multiple enabled datasets are ordered by priority. For duplicate tags, the -topmost dataset supplies the completion entry and its metadata. - -Autocomplete can be disabled globally in ComfyUI settings or from -`Edit β†’ Prompt Autocomplete` inside the Regional Editor. Disable it when another -completion extension should own prompt fields. BV Autocomplete also attaches to -ordinary ComfyUI multiline text widgets. Custom widgets can opt out with -`data-bv-autocomplete="off"` on the textarea or one of its ancestors. - -See [Regional Editor MVP](docs/regional-editor-mvp.md) for the document contract, -interaction details, model limitations, and validation scope. - ---- - -## Latent Nodes - -> A Collection of Latent Nodes. - -
-BV Latent Random Rotate 90 - -**Purpose** -- Rotates a latent by 90 degrees deterministically based on seed if enabled - -**Input** -- `latent` (LATENT) -- `seed` (INT) -- `enabled` (BOOLEAN) - -**Output** -- `latent` (`LATENT`) -- `latent_width` (`INT`) -- `latent_height` (`INT`) - - -
- -
-BV Empty Latent Random Ratio - -**Purpose** -- Creates a native empty latent at a deterministic aspect ratio -- Preserves the approximate pixel area of a square resolution reference -- Supports 512, 768, 1024, 1536, 2048, and a custom resolution - -**Input** -- `seed` (INT) -- `resolution` (512, 768, 1024, 1536, 2048, or Custom) -- `custom_resolution` (INT, used for Custom) -- `alignment` (8, 16, 32, or 64; default 8) -- Individual toggles for 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, 21:9, and 9:21 -- `ratios` (optional multiline STRING for additional normalized `W:H` ratios) -- `batch_size` (INT) - -**Output** -- `latent` (LATENT) -- `width` (INT, pixels) -- `height` (INT, pixels) -- `picked_ratio` (STRING) - -
- -`BV Latent Random Aspect Ratio` remains available for existing workflows but is deprecated. - -## Util Nodes - -> A Collection of Utility Nodes. - -
-BV Seed - -A Subgraph-capable seed controller with fast controls inspired by rgthree's Seed node. - -- `-1` remains visible and stored as the random-each-queue sentinel instead of being replaced after execution -- Quick actions select random-each-time, generate a new fixed random seed, or reuse the last queued seed -- The complete control β€” editable seed value and all three actions β€” is projected onto Subgraph nodes -- Only one public control is exposed: it is stored internally as `seed_bv` and displayed as `seed` -- At queue time, the frontend materializes a concrete value into the API prompt while leaving the saved UI state untouched -- The node still outputs a regular `INT` seed for samplers and other seed consumers - -
- -
-BV Hex Color To Int - -**Purpose** -- Converts a three- or six-digit HEX color code to an INT value - -**Input** -- `hex` (STRING, `#RGB`, `RGB`, `#RRGGBB`, or `RRGGBB`) - -**Output** -- `color` (`INT`) - - -
- -## Control Nodes - -
-BV Control Center - -Centralized runtime control for explicit **activate / mute / bypass** states of node groups. - -**Key Features** -- User-defined, case-sensitive Controls with stable IDs -- Stable group assignments displayed with their full graph/subgraph path -- Multiple synchronized Control Center nodes and subgraph exposure -- Controls participate only while their toggle is `ACTIVE`; `INACTIVE` Controls do not apply assignments -- Deterministic overlap resolution with `Activate > Mute > Bypass` -- Conflicting active assignments are explained in the Rack and in a persistent Node status row -- Optional Force Active behavior; otherwise each node's base mode is restored -- Unresolved groups remain visible and block execution while their Control is active -- Event-driven updates without polling or retry loops - -**Configure workflow states** - -![Control Center Rack configuration](examples/images/control-center-config.png) - -1. Create a named Control such as `Generate only` or `Full pipeline`. -2. Assign one or more graph or Subgraph groups. -3. Choose `Activate`, `Mute`, or `Bypass` for each assignment. -4. Save once; every synchronized Control Center node updates immediately. - -![Control Center graph state](examples/images/control-center-workflow-states.png) - -
- ---- - -## Quick Start (BV Smart Pipe) - -For new workflows, add **BV Smart Pipe**, open **Configure Smart Pipe**, and add -only the slots needed at that point in the chain. The following legacy setup is -kept for existing workflows only. - -1. Add **BV Pipe Config** and enter slot names: - -```txt -model -clip -vae -seed -prompt -``` - -2. Connect: - -`BV Pipe Config (pipe)` β†’ `BV Pipe (pipe)` - -3. Optionally override individual slots. - ---- - -## Notes & Design Principles - -- Smart Pipe slots use stable logical IDs; `v_001…` are only their persisted physical connector ordinals. -- Legacy `BV Pipe` retains its fixed 100-slot contract solely for existing workflows. -- Labels are user-defined and dynamic -- UI nodes are rendered via JavaScript -- All UI nodes support Subgraphs / Subflows -- Prompt nodes operate on **AST**, not raw strings - ---- +## Latent and utility nodes + +| Node | Purpose | +| --- | --- | +| BV Empty Latent Random Ratio | Selects enabled aspect ratios deterministically while preserving approximate square pixel area | +| BV Latent Random Rotate 90 | Applies a seed-controlled 90-degree latent rotation | +| BV Seed | Provides fixed, random-each-queue and last-queued modes with Subgraph projection | +| BV Hex Color To Int | Converts three- or six-digit hex colors to integers | + +[![Random-ratio latent](examples/images/empty-latent-random-ratio.png)](examples/images/empty-latent-random-ratio.png) + +`BV Latent Random Aspect Ratio` is deprecated but retained for workflow compatibility. + +## Example workflows + +Workflow PNGs contain importable ComfyUI metadata; matching JSON files are provided +as metadata-independent fallbacks. + +| Example | Preview | JSON | +| --- | --- | --- | +| Smart Pipe wireless merge | [PNG](examples/images/smart-pipe-wireless-merge.png) | [JSON](examples/workflows/smart-pipe-wireless-merge.json) | +| Control Center states | [PNG](examples/images/control-center-workflow-states.png) | [JSON](examples/workflows/control-center-workflow-states.json) | +| Subgraph UI layout | [PNG](examples/images/subgraph-ui-layout.png) | [JSON](examples/workflows/subgraph-ui-layout.json) | +| Random-ratio latent | [PNG](examples/images/empty-latent-random-ratio.png) | [JSON](examples/workflows/empty-latent-random-ratio.json) | +| Prompt AST categories | [PNG](examples/images/prompt-ast-categories.png) | [JSON](examples/workflows/prompt-ast-categories.json) | +| Anima regional android dance | [Workflow PNG](examples/images/anima-android-dance-regional-showcase.png) | [Regional document](docs/examples/anima-android-dance-regional-showcase.bv-regional.json) | + +Regional document fixtures: + +- [Anima: android dance with interaction overlap and painted light arc](docs/examples/anima-android-dance-regional-showcase.bv-regional.json) +- [Anima: two characters in a space station](docs/examples/anima-two-characters-space-station.bv-regional.json) +- [Krea 2: two women at a castle](docs/examples/krea2-two-women-castle.bv-regional.json) + +## Architecture and compatibility + +- Stable IDs are authoritative; names and labels are presentation. +- UI state is stored separately from semantic workflow documents. +- Optional model integrations load lazily and cannot prevent unrelated nodes from registering. +- Standard KSampler compatibility depends on the selected compiler/backend. +- Missing capabilities fail visibly instead of silently degrading prompt meaning. +- Nodes 2.0 and Subgraph behavior are tested independently from root-node rendering. + +Technical references: + +- [Regional schema v1](docs/specs/bv-regional-v1.md) +- [Global completion contract](docs/specs/bv-global-completion.md) +- [Regional Editor implementation notes](docs/regional-editor-mvp.md) +- [Smart Pipe contract ADR](docs/adr/0001-separate-smart-pipe-contract.md) +- [Renderer-independent Subgraph UI ADR](docs/adr/0002-renderer-independent-subgraph-ui.md) +- [Wireless Smart Pipe ADR](docs/adr/0003-wireless-smart-pipe-spine.md) +- [Third-party notices](THIRD_PARTY_NOTICES.md) + +## Current scope + +- Regional overlap execution currently supports `joint`; other modes are reserved. +- Native regional conditioning provides masks, not model-internal attention isolation. +- The built-in patched attention backend currently targets Anima. +- Regional negative isolation depends on backend capability. +- Region placement, overlap and strength guide conditioning but cannot guarantee + exact object boundaries, poses, depth order or pixel-perfect interactions. +- Wireless Smart Pipe compatibility remains sensitive to upstream prompt lifecycle changes. ## Changelog +### 2026-08-17 β€” v0.3.2 + +- Add Registry icon and 21:9 Nodes Manager banner metadata. +- Publish the illustrated Regional Editor, Anima workflow and autocomplete documentation. +- Preserve Quick Edit synchronization and background-image display state across editor sessions. +- Extend selected brush layers and expose background-image opacity controls. + ### 2026-08-17 β€” v0.3.1 + - Extend BV Prompt Autocomplete to ordinary ComfyUI multiline text widgets. -- Keep keyboard handling inside the active completion popup and provide an explicit widget opt-out. +- Keep completion keyboard handling local and provide explicit widget opt-out. - Clean up listeners when nodes are removed and prevent duplicate adapter installation. ### 2026-08-17 β€” v0.3.0 + - Add the BV-owned lazy CSV/TSV completion provider with extensible metadata. -- Add global and editor-local controls for disabling prompt autocomplete. -- Bundle `bv_default_tags.csv` so completion has no runtime dependency on another custom-node package. +- Add global/editor controls and ordered completion datasets. +- Bundle `bv_default_tags.csv` so completion has no runtime dependency on another node pack. -### 2026-08-17 -- v0.2.0 β€” Add the model-neutral BV Regional Editor and document toolchain. -- Add native masked-conditioning and built-in Anima attention backends for standard KSampler workflows. -- Add Quick Edit plus preview/save image senders with stable editor targeting. -- Add the first optional prompt-autocomplete provider bridge. +### 2026-08-17 β€” v0.2.0 -### 2026-08-14 -- v0.1.0 β€” Add BV Smart Pipe and native random-ratio empty latents; harden AST, Dynamic Combo, Subgraph UI, Control Rack, debug, rotation, and HEX nodes. +- Add the model-neutral Regional Editor and document toolchain. +- Add native masked conditioning and built-in Anima attention backends. +- Add Quick Edit and preview/save image feedback senders. -### 2026-01-29 -- v0.0.24 β€” Make subgraph UI widgets more rebuild-safe. +### 2026-08-14 β€” v0.1.0 -### 2026-01-11 -- v0.0.23 β€” Add BV Latent Random Aspect Ratio node. -- v0.0.22 β€” Change the category of BV Dynamic Combo. Add 90 Latent Rotate Node. +- Add Smart Pipe and native random-ratio empty latents. +- Harden AST, Dynamic Combo, Subgraph UI, Control Center, debug, rotation and hex nodes. -### 2026-01-10 -- v0.0.21 β€” Add dynamic combo box node -- v0.0.20 β€” Add a HEX color to INT node +Earlier history remains available in the Git log. -### 2026-01-02 -- v0.0.19 β€” Update README: add AST example image with embedded workflow -- v0.0.18 β€” Add AST Prompting system -- v0.0.17 β€” Changed toggle label system (`BV Control Center`) -- v0.0.16 β€” Renamed inputs to avoid collisions +## Acknowledgements -### 2026-01-01 -- v0.0.15 β€” Fix subgraph renaming bug -- v0.0.14 β€” Widget fixes for subgraph usage +BV Node Pack is built on ComfyUI's extension ecosystem. Several open-source +projects helped shape its product ideas, interaction patterns and technical research: -### 2025-12-31 -- v0.0.13 β€” Fix label inversion error -- v0.0.12 β€” Fix input error -- v0.0.11 β€” Reworked renaming logic +- [ComfyUI](https://github.com/Comfy-Org/ComfyUI) and + [ComfyUI Frontend](https://github.com/Comfy-Org/ComfyUI_frontend) provide the + runtime, graph, Subgraph and extension foundations this pack integrates with. +- [rgthree-comfy](https://github.com/rgthree/rgthree-comfy) influenced the focus on + fast workflow controls, compact graph tooling and practical seed/control UX. +- [ComfyUI_agilly1989_motorway](https://github.com/agilly1989/ComfyUI_agilly1989_motorway) + was the original inspiration for configurable BV Pipes. Motorway demonstrated + that a pipe could carry user-named values through a workflow and overwrite an + existing key downstream instead of relying only on a permanently fixed port set. + BV Smart Pipe developed that idea further with incremental slot inheritance, + stable slot identities, independent branches, wireless routing and explicit merges. +- [cg-use-everywhere](https://github.com/chrisgoringe/cg-use-everywhere), commonly + known as Use Everywhere, inspired the wireless-routing direction. Its approach + demonstrated how values can be broadcast without visible graph links and how + routing rules can disambiguate targets in complex workflows. BV Smart Pipe uses + its own explicit predecessor, stable-address and branch/merge semantics. +- [ComfyUI-KJNodes](https://github.com/kijai/ComfyUI-KJNodes), especially the + Ideogram regional prompt-builder workflow, inspired the idea of a dedicated + editor surface that can remain available while navigating the graph. +- [ComfyUI_LC123_nodes](https://github.com/lonecatone23/ComfyUI_LC123_nodes) + demonstrated painted regional authoring and provided useful Krea 2 and Anima + workflow references. +- [Comfyui-Anima-Regional-Conditioning](https://github.com/Sen-sou/Comfyui-Anima-Regional-Conditioning) + provided the technical basis for the built-in Anima patch. Its MIT attribution + is reproduced in [Third-Party Notices](THIRD_PARTY_NOTICES.md). +- [RES4LYF](https://github.com/ClownsharkBatwing/RES4LYF) was studied as an + architectural reference for regional attention, overlap and model-specific + backends. BV does not copy its implementation. +- [comfy-ex-tagcomplete](https://github.com/jupo-ai/comfy-ex-tagcomplete) informed + completion behavior and supplied the baseline public tag-data snapshot. BV uses + its own completion implementation; dataset provenance is documented separately. -### 2025-12-30 -- v0.0.10 β€” Fix widget create event +> **Thank you.** BV Node Pack would not have grown into its current form without +> the maintainers, researchers and workflow creators who share their code, ideas, +> experiments and hard-earned findings with the ComfyUI community. Their openness +> made it possible to study different approaches, learn from them and build something +> new on top of that collective knowledge. We sincerely appreciate the time and care +> behind every project acknowledged above. -### 2025-12-29 -- v0.0.9 β€” Fix subgraph issues -- v0.0.8 β€” Major refactor to TypeScript +Inspiration acknowledgements do not imply endorsement, affiliation or a runtime +dependency unless explicitly stated. +## License + +BV Node Pack is licensed under **GNU GPL v3**. Third-party-derived components and +datasets are documented in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md index 5cff8da..a2a1849 100644 --- a/THIRD_PARTY_NOTICES.md +++ b/THIRD_PARTY_NOTICES.md @@ -1,5 +1,10 @@ # Third-party notices +This file records third-party code or data incorporated into BV Node Pack and the +licenses or provenance obligations that accompany it. Projects that influenced +design or research without contributing copied code are acknowledged separately +below and in the README. + ## Baseline completion tag data `data/completion/bv_default_tags.csv` was sourced from the @@ -37,3 +42,27 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +## Inspiration and research acknowledgements + +The following projects informed product design, interoperability research or +architecture discussions. They are not bundled runtime dependencies, and no copied +implementation is claimed unless another section of this file says otherwise. + +- [`rgthree-comfy`](https://github.com/rgthree/rgthree-comfy): compact workflow, + control and seed interaction patterns. +- [`ComfyUI_agilly1989_motorway`](https://github.com/agilly1989/ComfyUI_agilly1989_motorway): + the original inspiration for configurable, user-named values carried and + overridden along BV Pipe chains. +- [`cg-use-everywhere`](https://github.com/chrisgoringe/cg-use-everywhere): + wireless value broadcasting and routing-control concepts that informed the + Smart Pipe wireless design. +- [`ComfyUI-KJNodes`](https://github.com/kijai/ComfyUI-KJNodes): the Ideogram + prompt-builder editor and detached authoring workflow. +- [`ComfyUI_LC123_nodes`](https://github.com/lonecatone23/ComfyUI_LC123_nodes): + painted regional authoring plus Krea 2 and Anima workflow references. +- [`RES4LYF`](https://github.com/ClownsharkBatwing/RES4LYF): clean-room research + reference for regional attention, overlap semantics and backend boundaries. +- [`comfy-ex-tagcomplete`](https://github.com/jupo-ai/comfy-ex-tagcomplete): + completion interoperability and UX research. Its bundled tag-data relationship + is documented in the first section of this file. diff --git a/docs/assets/bv-nodepack-hero.svg b/docs/assets/bv-nodepack-hero.svg new file mode 100644 index 0000000..9db7352 --- /dev/null +++ b/docs/assets/bv-nodepack-hero.svg @@ -0,0 +1,64 @@ + + BV Node Pack for ComfyUI + A dark ComfyUI-inspired workflow showing regional prompting, structured prompts, smart pipes and subgraph controls. + + + + + + + + + + + + + + + + BV Node Pack + Deep workflow tools for ComfyUI + + + + + + + Regional Prompt + GLOBAL + REGIONS + + + + + + + + BV Regional Editor + + LAYERS + + + + + + PROMPT + + + + + + + Anima Conditioning + MODEL + CLIP + BV_REGIONAL + + + + + + + Regional prompting Β· Prompt AST Β· Smart Pipes Β· Subgraph UI Β· Local autocomplete + + diff --git a/docs/assets/regional/SHOT-LIST.md b/docs/assets/regional/SHOT-LIST.md new file mode 100644 index 0000000..e4bb4ef --- /dev/null +++ b/docs/assets/regional/SHOT-LIST.md @@ -0,0 +1,39 @@ +# Regional documentation shot list + +This file tracks the current documentation screenshots and optional future additions. +Capture at 100% browser scale with unrelated panels closed and no personal paths, +usernames, seeds or model filenames visible unless they are intentional. + +## Present assets + +- `editor-workspace.png`, `editor-floating.png` β€” both editor layouts. +- `view-controls.png` β€” mask and background-image display opacity. +- `regional-prompt-node.png`, `toolbar-*.png`, `quick-edit.png` β€” editor entry points. +- `region-*.png` β€” main rectangles, interaction rectangles and painted light arc. +- `autocomplete-*.png` β€” Quick Edit, full editor and native multiline completion. +- `completion-settings.png` β€” dataset selection, priority and global enable switch. +- `anima-workflow.png` β€” minimal Anima regional execution graph. +- `../../../examples/images/anima-android-dance-regional-showcase.png` β€” final + metadata-bearing workflow PNG and reference result. + +## Still needed + +1. `minimal-native-workflow.png` + - Regional Prompt β†’ Native Conditioning β†’ standard KSampler. +2. `editor-tools.png` + - One rectangle, one additive brush and a subtractive split; show selection handles. +3. `image-feedback.png` + - Preview/Save Send target selector plus the resulting editor background. +4. `document-tools.png` + - Deconstructor, Prompt Extract and Mask Render with representative outputs. +5. `completion-priority.png` + - At least two datasets so the ordering controls and priority rule are visible. + +## Replacement quality bar + +- Prefer 16:9 or a tight landscape crop. +- Use English UI labels. +- Avoid open menus unless the menu itself is the subject. +- Show one concept per image. +- Ensure cables do not obscure node titles or controls. +- Use the same dark ComfyUI theme and zoom level throughout a sequence. diff --git a/docs/assets/regional/anima-workflow.png b/docs/assets/regional/anima-workflow.png new file mode 100644 index 0000000..007fbd2 Binary files /dev/null and b/docs/assets/regional/anima-workflow.png differ diff --git a/docs/assets/regional/autocomplete-editor.png b/docs/assets/regional/autocomplete-editor.png new file mode 100644 index 0000000..136648f Binary files /dev/null and b/docs/assets/regional/autocomplete-editor.png differ diff --git a/docs/assets/regional/autocomplete-multiline.png b/docs/assets/regional/autocomplete-multiline.png new file mode 100644 index 0000000..cb58ae6 Binary files /dev/null and b/docs/assets/regional/autocomplete-multiline.png differ diff --git a/docs/assets/regional/autocomplete-quick-edit.png b/docs/assets/regional/autocomplete-quick-edit.png new file mode 100644 index 0000000..d754d6c Binary files /dev/null and b/docs/assets/regional/autocomplete-quick-edit.png differ diff --git a/docs/assets/regional/completion-settings.png b/docs/assets/regional/completion-settings.png new file mode 100644 index 0000000..f07ad4e Binary files /dev/null and b/docs/assets/regional/completion-settings.png differ diff --git a/docs/assets/regional/editor-floating.png b/docs/assets/regional/editor-floating.png new file mode 100644 index 0000000..ddceac9 Binary files /dev/null and b/docs/assets/regional/editor-floating.png differ diff --git a/docs/assets/regional/editor-workspace.png b/docs/assets/regional/editor-workspace.png new file mode 100644 index 0000000..ee73abf Binary files /dev/null and b/docs/assets/regional/editor-workspace.png differ diff --git a/docs/assets/regional/quick-edit.png b/docs/assets/regional/quick-edit.png new file mode 100644 index 0000000..7880cec Binary files /dev/null and b/docs/assets/regional/quick-edit.png differ diff --git a/docs/assets/regional/region-amber-interaction.png b/docs/assets/regional/region-amber-interaction.png new file mode 100644 index 0000000..206d9d8 Binary files /dev/null and b/docs/assets/regional/region-amber-interaction.png differ diff --git a/docs/assets/regional/region-amber-main.png b/docs/assets/regional/region-amber-main.png new file mode 100644 index 0000000..db1fa0b Binary files /dev/null and b/docs/assets/regional/region-amber-main.png differ diff --git a/docs/assets/regional/region-brush-arc.png b/docs/assets/regional/region-brush-arc.png new file mode 100644 index 0000000..ae18d44 Binary files /dev/null and b/docs/assets/regional/region-brush-arc.png differ diff --git a/docs/assets/regional/region-cyan-interaction.png b/docs/assets/regional/region-cyan-interaction.png new file mode 100644 index 0000000..46dab5d Binary files /dev/null and b/docs/assets/regional/region-cyan-interaction.png differ diff --git a/docs/assets/regional/region-cyan-main.png b/docs/assets/regional/region-cyan-main.png new file mode 100644 index 0000000..ddceac9 Binary files /dev/null and b/docs/assets/regional/region-cyan-main.png differ diff --git a/docs/assets/regional/regional-prompt-node.png b/docs/assets/regional/regional-prompt-node.png new file mode 100644 index 0000000..071eb10 Binary files /dev/null and b/docs/assets/regional/regional-prompt-node.png differ diff --git a/docs/assets/regional/toolbar-actions.png b/docs/assets/regional/toolbar-actions.png new file mode 100644 index 0000000..f6c4df6 Binary files /dev/null and b/docs/assets/regional/toolbar-actions.png differ diff --git a/docs/assets/regional/toolbar-editor-hover.png b/docs/assets/regional/toolbar-editor-hover.png new file mode 100644 index 0000000..1fcc2c0 Binary files /dev/null and b/docs/assets/regional/toolbar-editor-hover.png differ diff --git a/docs/assets/regional/toolbar-quick-hover.png b/docs/assets/regional/toolbar-quick-hover.png new file mode 100644 index 0000000..918a05a Binary files /dev/null and b/docs/assets/regional/toolbar-quick-hover.png differ diff --git a/docs/assets/regional/view-controls.png b/docs/assets/regional/view-controls.png new file mode 100644 index 0000000..c8d6f43 Binary files /dev/null and b/docs/assets/regional/view-controls.png differ diff --git a/docs/assets/registry/bv-nodepack-banner.png b/docs/assets/registry/bv-nodepack-banner.png new file mode 100644 index 0000000..87ca2d8 Binary files /dev/null and b/docs/assets/registry/bv-nodepack-banner.png differ diff --git a/docs/assets/registry/bv-nodepack-banner.svg b/docs/assets/registry/bv-nodepack-banner.svg new file mode 100644 index 0000000..77e62ab --- /dev/null +++ b/docs/assets/registry/bv-nodepack-banner.svg @@ -0,0 +1,108 @@ + + BV Node Pack for ComfyUI + A dark 21:9 banner presenting BV Node Pack and its regional prompting editor. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + BV Node Pack + Advanced workflow tools for ComfyUI + + + + + Design prompts spatially. + Keep workflows modular. + + Regional prompting, structured prompts, + Smart Pipes and subgraph-aware controls. + + + + Regional Editor + + Prompt AST + + Smart Pipes + + + + + + + + + BV Regional Editor + + Workspace + + + REGIONS + + Cyan subject + + Amber subject + + Light arc + + + + + + + + + + + + + + REGION PROMPT + Strength + + 0.85 + Positive + + + Negative + + + + + + + + + + diff --git a/docs/assets/registry/bv-nodepack-icon.png b/docs/assets/registry/bv-nodepack-icon.png new file mode 100644 index 0000000..e6c2f11 Binary files /dev/null and b/docs/assets/registry/bv-nodepack-icon.png differ diff --git a/docs/assets/registry/bv-nodepack-icon.svg b/docs/assets/registry/bv-nodepack-icon.svg new file mode 100644 index 0000000..12ef647 --- /dev/null +++ b/docs/assets/registry/bv-nodepack-icon.svg @@ -0,0 +1,20 @@ + + BV Node Pack + BV Node Pack spiral mark on a dark rounded-square background. + + + + + + + + + + + + + + + + + diff --git a/docs/examples/anima-android-dance-regional-showcase.bv-regional.json b/docs/examples/anima-android-dance-regional-showcase.bv-regional.json new file mode 100644 index 0000000..e847f56 --- /dev/null +++ b/docs/examples/anima-android-dance-regional-showcase.bv-regional.json @@ -0,0 +1,1395 @@ +{ + "canvas": { + "width": 1024, + "height": 1024 + }, + "document_id": "90bf8116-b704-49fc-b686-f1abc72cd893", + "negative_mode": "auto", + "overlap": { + "mode": "joint" + }, + "prompts": { + "global": { + "positive_source": "masterpiece, best quality, exactly two female humanoid android dancers performing an elegant synchronized duet, full body, both completely visible, reaching toward each other, their hands meeting naturally, dynamic flowing poses, cinematic science-fiction fashion photography, SFW", + "negative_source": "third person, extra person, duplicate person, fused bodies, merged faces, mixed character design, extra arms, extra hands, malformed hands, missing fingers, cropped, out of frame, blurry, lowres, text, watermark, NSFW" + }, + "background": { + "positive_source": "futuristic circular performance stage inside a space station, panoramic windows, distant stars and a blue planet, reflective metallic floor, dramatic rim lighting", + "negative_source": "" + } + }, + "regions": [ + { + "id": "e35b2648-2e04-45de-9ac9-784f098676cf", + "name": "Cyan Porcelain Android", + "parent_region_id": null, + "enabled": true, + "priority": 0, + "strength": 0.85, + "mask": { + "feather": 0.02 + }, + "authoring": { + "color": "#4C78A8", + "visible": true, + "locked": false + }, + "prompts": { + "positive_source": "female humanoid android made from smooth white porcelain panels, vivid cyan luminous circuit lines, long cobalt-blue synthetic hair, translucent cyan fabric ribbons, elegant futuristic dance costume", + "negative_source": "orange glow, black armor, red hair" + }, + "geometry": [ + { + "id": "3c2244db-d967-4f40-bf39-aa41d067d558", + "layer_id": "6cdf0298-a231-42cc-9ea0-63517a2268c7", + "type": "rect", + "operation": "add", + "enabled": true, + "x": 0.06, + "y": 0.1, + "width": 0.46, + "height": 0.84, + "authoring": { + "name": "Main body", + "visible": true, + "locked": false + } + }, + { + "id": "b68400d9-d7fc-4a75-89bf-a9aa8ed83db6", + "layer_id": "3172e13c-0839-43d8-9f59-ba050a3be5bd", + "type": "rect", + "operation": "add", + "enabled": true, + "x": 0.42, + "y": 0.28, + "width": 0.18, + "height": 0.3, + "authoring": { + "name": "Interaction area", + "visible": true, + "locked": false + } + } + ] + }, + { + "id": "cb015b26-f94d-4a64-87e2-aaf785520a53", + "name": "Amber Obsidian Android", + "parent_region_id": null, + "enabled": true, + "priority": 1, + "strength": 0.85, + "mask": { + "feather": 0.02 + }, + "authoring": { + "color": "#E45756", + "visible": true, + "locked": false + }, + "prompts": { + "positive_source": "female humanoid android made from glossy obsidian-black armor, vivid amber-orange luminous circuit lines, short crimson synthetic hair, translucent orange fabric ribbons, elegant futuristic dance costume", + "negative_source": "cyan glow, white porcelain armor, blue hair" + }, + "geometry": [ + { + "id": "06c6e273-6687-4a47-95e3-7a102dd20cb9", + "layer_id": "0eed2b99-afaf-4554-8435-995d206677b6", + "type": "rect", + "operation": "add", + "enabled": true, + "x": 0.48, + "y": 0.1, + "width": 0.46, + "height": 0.84, + "authoring": { + "name": "Main body", + "visible": true, + "locked": false + } + }, + { + "id": "e34fd948-f7b6-4c03-b3cb-854d87149928", + "layer_id": "d52927ac-0ae4-4c58-bf7a-6da9866a703b", + "type": "rect", + "operation": "add", + "enabled": true, + "x": 0.4, + "y": 0.28, + "width": 0.18, + "height": 0.3, + "authoring": { + "name": "Interaction area", + "visible": true, + "locked": false + } + } + ] + }, + { + "id": "cd9b9e29-7457-47da-9d50-193560b54689", + "name": "Holographic Light Arc", + "parent_region_id": null, + "enabled": true, + "strength": 0.6, + "priority": 2, + "prompts": { + "positive_source": "soft golden holographic light ribbon, glowing energy arc, subtle luminous particles, gentle bloom, elegant science-fiction illumination", + "negative_source": "person, face, body, creature, solid object, text, logo" + }, + "mask": { + "feather": 0.02 + }, + "geometry": [ + { + "id": "670b1740-84e4-43f3-8bb2-0d3a96d42e4d", + "layer_id": "670b1740-84e4-43f3-8bb2-0d3a96d42e4d", + "type": "brush_stroke", + "operation": "add", + "enabled": true, + "authoring": { + "name": "Brush Arc", + "visible": true, + "locked": false + }, + "size": 0.06, + "hardness": 0.65, + "opacity": 0.8, + "shape": "round", + "pressure_mode": "constant", + "points": [ + { + "x": 0.08290633087386516, + "y": 0.21850712432371053, + "pressure": 1 + }, + { + "x": 0.0979660423981448, + "y": 0.18954614267087422, + "pressure": 1 + }, + { + "x": 0.15820488849526337, + "y": 0.1432085720263361, + "pressure": 1 + }, + { + "x": 0.17905679675965055, + "y": 0.13046574009908812, + "pressure": 1 + }, + { + "x": 0.19759182632799474, + "y": 0.12351510450240742, + "pressure": 1 + }, + { + "x": 0.2172852952443604, + "y": 0.11077227257515944, + "pressure": 1 + }, + { + "x": 0.225394370680511, + "y": 0.10845539404293253, + "pressure": 1 + }, + { + "x": 0.23466188546468308, + "y": 0.10150475844625181, + "pressure": 1 + }, + { + "x": 0.29837604960586617, + "y": 0.0725437767934155, + "pressure": 1 + }, + { + "x": 0.3505058202668342, + "y": 0.057484066333940625, + "pressure": 1 + }, + { + "x": 0.4269628172362539, + "y": 0.04242435587446574, + "pressure": 1 + }, + { + "x": 0.4605575583288777, + "y": 0.041265916608352285, + "pressure": 1 + }, + { + "x": 0.48720166333337245, + "y": 0.03663215954389848, + "pressure": 1 + }, + { + "x": 0.5416483126903835, + "y": 0.03663215954389848, + "pressure": 1 + }, + { + "x": 0.5625002209547707, + "y": 0.03199840247944467, + "pressure": 1 + }, + { + "x": 0.5949365226993729, + "y": 0.03315684174555812, + "pressure": 1 + }, + { + "x": 0.606520916179588, + "y": 0.029681523947217764, + "pressure": 1 + }, + { + "x": 0.6713935196687927, + "y": 0.041265916608352285, + "pressure": 1 + }, + { + "x": 0.6795025951049433, + "y": 0.04474123440669264, + "pressure": 1 + }, + { + "x": 0.7304739264178898, + "y": 0.04705811293891955, + "pressure": 1 + }, + { + "x": 0.7605933494664491, + "y": 0.05169187000337336, + "pressure": 1 + }, + { + "x": 0.7698608642506211, + "y": 0.06095938413228098, + "pressure": 1 + }, + { + "x": 0.7768115003387501, + "y": 0.06211782339839443, + "pressure": 1 + }, + { + "x": 0.7814452577308362, + "y": 0.06906845899507515, + "pressure": 1 + }, + { + "x": 0.7895543331669868, + "y": 0.0702268982611886, + "pressure": 1 + }, + { + "x": 0.7930296512110513, + "y": 0.07486065532564241, + "pressure": 1 + }, + { + "x": 0.8011387266472019, + "y": 0.07601909459175586, + "pressure": 1 + }, + { + "x": 0.8219906349115891, + "y": 0.08760348725289038, + "pressure": 1 + }, + { + "x": 0.8254659529556536, + "y": 0.0922372443173442, + "pressure": 1 + }, + { + "x": 0.8300997103477397, + "y": 0.0922372443173442, + "pressure": 1 + }, + { + "x": 0.8416841038279548, + "y": 0.09918787991402492, + "pressure": 1 + }, + { + "x": 0.8474763005680623, + "y": 0.10961383330904599, + "pressure": 1 + }, + { + "x": 0.862536012092342, + "y": 0.1188813474379536, + "pressure": 1 + }, + { + "x": 0.8660113301364065, + "y": 0.12583198303463433, + "pressure": 1 + }, + { + "x": 0.8799126023126647, + "y": 0.1385748149618823, + "pressure": 1 + }, + { + "x": 0.8799126023126647, + "y": 0.1408916934941092, + "pressure": 1 + }, + { + "x": 0.8857047990527722, + "y": 0.1432085720263361, + "pressure": 1 + }, + { + "x": 0.8857047990527722, + "y": 0.14784232909078993, + "pressure": 1 + }, + { + "x": 0.8938138744889228, + "y": 0.16174360028415136, + "pressure": 1 + }, + { + "x": 0.9007645105770519, + "y": 0.1652189180824917, + "pressure": 1 + }, + { + "x": 0.9053982679691379, + "y": 0.17216955367917242, + "pressure": 1 + }, + { + "x": 0.9077151466651809, + "y": 0.17216955367917242, + "pressure": 1 + }, + { + "x": 0.910032025361224, + "y": 0.17796175000973968, + "pressure": 1 + }, + { + "x": 0.9111904647092455, + "y": 0.17680331074362624, + "pressure": 1 + } + ] + }, + { + "id": "f6544aa8-b6b7-478c-84f7-71f049a92302", + "layer_id": "670b1740-84e4-43f3-8bb2-0d3a96d42e4d", + "type": "brush_stroke", + "operation": "add", + "enabled": true, + "authoring": { + "name": "Brush Arc", + "visible": true, + "locked": false + }, + "size": 0.06, + "hardness": 0.65, + "opacity": 0.8, + "shape": "round", + "pressure_mode": "constant", + "points": [ + { + "x": 0.06321286195749948, + "y": 0.17332799294528586, + "pressure": 1 + }, + { + "x": 0.06437130130552099, + "y": 0.16869423588083207, + "pressure": 1 + }, + { + "x": 0.09217384565803724, + "y": 0.14205013276022266, + "pressure": 1 + }, + { + "x": 0.10144136044220933, + "y": 0.1362579364296554, + "pressure": 1 + }, + { + "x": 0.1083919965303384, + "y": 0.12583198303463433, + "pressure": 1 + }, + { + "x": 0.1315607834907686, + "y": 0.10498007624459217, + "pressure": 1 + }, + { + "x": 0.14662049501504826, + "y": 0.09571256211568456, + "pressure": 1 + }, + { + "x": 0.21265153785227436, + "y": 0.0702268982611886, + "pressure": 1 + }, + { + "x": 0.32733703330640396, + "y": 0.030839963213331215, + "pressure": 1 + }, + { + "x": 0.44202252876053355, + "y": 0.020414009818310142, + "pressure": 1 + }, + { + "x": 0.4814094665932649, + "y": 0.008829617157175618, + "pressure": 1 + }, + { + "x": 0.5358561159502759, + "y": 0.0030374208266083546, + "pressure": 1 + }, + { + "x": 0.6528584901004485, + "y": 0.0007205422943814494, + "pressure": 1 + }, + { + "x": 0.7003545033693305, + "y": 0.008829617157175618, + "pressure": 1 + }, + { + "x": 0.7246817296777822, + "y": 0.008829617157175618, + "pressure": 1 + }, + { + "x": 0.7432167592461264, + "y": 0.011146495689402522, + "pressure": 1 + }, + { + "x": 0.7466920772901909, + "y": 0.01462181348774288, + "pressure": 1 + }, + { + "x": 0.7721777429466641, + "y": 0.015780252753856333, + "pressure": 1 + }, + { + "x": 0.7872374544709437, + "y": 0.021572449084423594, + "pressure": 1 + }, + { + "x": 0.81503999882346, + "y": 0.04010747734223884, + "pressure": 1 + }, + { + "x": 0.8254659529556536, + "y": 0.043582795140579195, + "pressure": 1 + }, + { + "x": 0.8567438153522344, + "y": 0.08181129092232313, + "pressure": 1 + }, + { + "x": 0.8718035268765141, + "y": 0.0945541228495711, + "pressure": 1 + }, + { + "x": 0.8810710416606862, + "y": 0.10845539404293253, + "pressure": 1 + }, + { + "x": 0.8949723138369443, + "y": 0.1142475903734998, + "pressure": 1 + }, + { + "x": 0.8996060712290304, + "y": 0.12699042230074778, + "pressure": 1 + }, + { + "x": 0.912348904057267, + "y": 0.13162417936520157, + "pressure": 1 + }, + { + "x": 0.9158242221013315, + "y": 0.13973325422799576, + "pressure": 1 + }, + { + "x": 0.9204579794934176, + "y": 0.1432085720263361, + "pressure": 1 + }, + { + "x": 0.9250917368855036, + "y": 0.15479296468747064, + "pressure": 1 + }, + { + "x": 0.9366761303657187, + "y": 0.1605851610180379, + "pressure": 1 + }, + { + "x": 0.9401514484097833, + "y": 0.17332799294528586, + "pressure": 1 + }, + { + "x": 0.9494189631939552, + "y": 0.1756448714775128, + "pressure": 1 + }, + { + "x": 0.9505774025419768, + "y": 0.17796175000973968, + "pressure": 1 + } + ] + }, + { + "id": "74d41f21-65a8-43f3-8f06-810e6fa748df", + "layer_id": "670b1740-84e4-43f3-8bb2-0d3a96d42e4d", + "type": "brush_stroke", + "operation": "add", + "enabled": true, + "authoring": { + "name": "Brush Arc", + "visible": true, + "locked": false + }, + "size": 0.06, + "hardness": 0.65, + "opacity": 0.8, + "shape": "round", + "pressure_mode": "constant", + "points": [ + { + "x": 0.8231490742596106, + "y": 0.07486065532564241, + "pressure": 1 + }, + { + "x": 0.8069309233873094, + "y": 0.06675158046284824, + "pressure": 1 + }, + { + "x": 0.7791283790347932, + "y": 0.05980094486616753, + "pressure": 1 + }, + { + "x": 0.7710193035986426, + "y": 0.05400874853560027, + "pressure": 1 + }, + { + "x": 0.7617517888144706, + "y": 0.05169187000337336, + "pressure": 1 + }, + { + "x": 0.7177310935896531, + "y": 0.021572449084423594, + "pressure": 1 + }, + { + "x": 0.6922454279331799, + "y": 0.013463374221629427, + "pressure": 1 + }, + { + "x": 0.6690766409727497, + "y": 0.008829617157175618, + "pressure": 1 + }, + { + "x": 0.6447494146642979, + "y": 0.008829617157175618, + "pressure": 1 + }, + { + "x": 0.6308481424880398, + "y": 0.012304934955515975, + "pressure": 1 + }, + { + "x": 0.6238975063999107, + "y": 0.016938692019969784, + "pressure": 1 + }, + { + "x": 0.6099962342236526, + "y": 0.016938692019969784, + "pressure": 1 + }, + { + "x": 0.6076793555276095, + "y": 0.02273088835053705, + "pressure": 1 + } + ] + }, + { + "id": "50836873-a556-450a-83c1-108bff5bd0ef", + "layer_id": "670b1740-84e4-43f3-8bb2-0d3a96d42e4d", + "type": "brush_stroke", + "operation": "add", + "enabled": true, + "authoring": { + "name": "Brush Arc", + "visible": true, + "locked": false + }, + "size": 0.06, + "hardness": 0.65, + "opacity": 0.8, + "shape": "round", + "pressure_mode": "constant", + "points": [ + { + "x": 0.45013160419668413, + "y": 0.0076711778910621645, + "pressure": 1 + }, + { + "x": 0.37019928918319983, + "y": 0.009988056423289069, + "pressure": 1 + }, + { + "x": 0.35513957765892024, + "y": 0.006512738624948712, + "pressure": 1 + }, + { + "x": 0.3400798661346406, + "y": 0.006512738624948712, + "pressure": 1 + }, + { + "x": 0.33197079069849, + "y": 0.009988056423289069, + "pressure": 1 + }, + { + "x": 0.3238617152623394, + "y": 0.009988056423289069, + "pressure": 1 + }, + { + "x": 0.3122773217821243, + "y": 0.027364645414990858, + "pressure": 1 + }, + { + "x": 0.30648512504201675, + "y": 0.029681523947217764, + "pressure": 1 + }, + { + "x": 0.277524141341479, + "y": 0.03779059881001193, + "pressure": 1 + }, + { + "x": 0.2659397478612639, + "y": 0.04474123440669264, + "pressure": 1 + }, + { + "x": 0.24277096090083367, + "y": 0.04474123440669264, + "pressure": 1 + }, + { + "x": 0.22886968872457553, + "y": 0.05053343073725991, + "pressure": 1 + }, + { + "x": 0.21149309850425288, + "y": 0.05169187000337336, + "pressure": 1 + }, + { + "x": 0.20685934111216683, + "y": 0.055167187801713716, + "pressure": 1 + }, + { + "x": 0.19527494763195172, + "y": 0.055167187801713716, + "pressure": 1 + }, + { + "x": 0.19179962958788718, + "y": 0.05632562706782717, + "pressure": 1 + }, + { + "x": 0.19064119023986567, + "y": 0.05980094486616753, + "pressure": 1 + }, + { + "x": 0.1616802065393279, + "y": 0.07486065532564241, + "pressure": 1 + }, + { + "x": 0.16283864588734942, + "y": 0.07717753385786931, + "pressure": 1 + }, + { + "x": 0.14662049501504826, + "y": 0.08296973018843658, + "pressure": 1 + }, + { + "x": 0.14893737371109128, + "y": 0.08644504798677694, + "pressure": 1 + }, + { + "x": 0.1304023441427471, + "y": 0.0922372443173442, + "pressure": 1 + }, + { + "x": 0.12345170805461804, + "y": 0.09802944064791146, + "pressure": 1 + }, + { + "x": 0.10723355718231689, + "y": 0.10150475844625181, + "pressure": 1 + }, + { + "x": 0.10259979979023084, + "y": 0.10613851551070563, + "pressure": 1 + }, + { + "x": 0.07363881608969307, + "y": 0.10729695477681908, + "pressure": 1 + }, + { + "x": 0.0655297406535425, + "y": 0.11193071184127289, + "pressure": 1 + }, + { + "x": 0.062054422609477966, + "y": 0.12003978670406706, + "pressure": 1 + }, + { + "x": 0.05162846847728436, + "y": 0.12235666523629396, + "pressure": 1 + }, + { + "x": 0.04583627173717681, + "y": 0.12814886156686123, + "pressure": 1 + }, + { + "x": 0.048153150433219834, + "y": 0.13162417936520157, + "pressure": 1 + }, + { + "x": 0.036568756953004725, + "y": 0.1339410578974285, + "pressure": 1 + }, + { + "x": 0.03888563564904775, + "y": 0.1408916934941092, + "pressure": 1 + }, + { + "x": 0.028459681516854147, + "y": 0.14900076835690337, + "pressure": 1 + }, + { + "x": 0.02961812086487566, + "y": 0.15247608615524372, + "pressure": 1 + }, + { + "x": 0.03541031760498321, + "y": 0.15479296468747064, + "pressure": 1 + }, + { + "x": 0.026142802820811124, + "y": 0.16174360028415136, + "pressure": 1 + }, + { + "x": 0.03541031760498321, + "y": 0.16869423588083207, + "pressure": 1 + }, + { + "x": 0.041202514345090764, + "y": 0.16985267514694552, + "pressure": 1 + }, + { + "x": 0.0342518782569617, + "y": 0.1756448714775128, + "pressure": 1 + }, + { + "x": 0.041202514345090764, + "y": 0.18027862854196658, + "pressure": 1 + }, + { + "x": 0.0342518782569617, + "y": 0.19186302120310111, + "pressure": 1 + }, + { + "x": 0.042360953693112276, + "y": 0.19649677826755493, + "pressure": 1 + }, + { + "x": 0.04351939304113379, + "y": 0.20113053533200873, + "pressure": 1 + }, + { + "x": 0.049311589781241345, + "y": 0.20344741386423565, + "pressure": 1 + }, + { + "x": 0.049311589781241345, + "y": 0.20923961019480292, + "pressure": 1 + }, + { + "x": 0.05973754391343494, + "y": 0.2138733672592567, + "pressure": 1 + }, + { + "x": 0.05742066521739192, + "y": 0.2138733672592567, + "pressure": 1 + }, + { + "x": 0.06668818000156401, + "y": 0.2138733672592567, + "pressure": 1 + }, + { + "x": 0.0771141341337576, + "y": 0.21039804946091636, + "pressure": 1 + }, + { + "x": 0.07363881608969307, + "y": 0.2046058531303491, + "pressure": 1 + }, + { + "x": 0.08406477022188667, + "y": 0.19997209606589528, + "pressure": 1 + }, + { + "x": 0.08985696696199423, + "y": 0.18954614267087422, + "pressure": 1 + }, + { + "x": 0.08869852761397272, + "y": 0.17912018927585313, + "pressure": 1 + }, + { + "x": 0.09217384565803724, + "y": 0.16753579661471862, + "pressure": 1 + }, + { + "x": 0.0979660423981448, + "y": 0.15942672175192443, + "pressure": 1 + }, + { + "x": 0.09449072435408026, + "y": 0.14784232909078993, + "pressure": 1 + }, + { + "x": 0.10259979979023084, + "y": 0.1362579364296554, + "pressure": 1 + }, + { + "x": 0.09912448174616631, + "y": 0.13046574009908812, + "pressure": 1 + }, + { + "x": 0.10723355718231689, + "y": 0.12235666523629396, + "pressure": 1 + }, + { + "x": 0.10955043587835991, + "y": 0.11772290817184015, + "pressure": 1 + }, + { + "x": 0.1083919965303384, + "y": 0.11308915110738635, + "pressure": 1 + }, + { + "x": 0.12576858675066105, + "y": 0.10266319771236528, + "pressure": 1 + }, + { + "x": 0.16747240327943547, + "y": 0.09687100138179801, + "pressure": 1 + }, + { + "x": 0.20570090176414532, + "y": 0.08760348725289038, + "pressure": 1 + }, + { + "x": 0.26014755112115634, + "y": 0.08181129092232313, + "pressure": 1 + }, + { + "x": 0.2937422922137801, + "y": 0.07370221605952895, + "pressure": 1 + }, + { + "x": 0.2740488232974145, + "y": 0.07717753385786931, + "pressure": 1 + }, + { + "x": 0.24161252155281215, + "y": 0.08876192651900384, + "pressure": 1 + }, + { + "x": 0.19759182632799474, + "y": 0.10034631918013837, + "pressure": 1 + }, + { + "x": 0.13619454088285465, + "y": 0.12814886156686123, + "pressure": 1 + }, + { + "x": 0.10607511783429538, + "y": 0.14900076835690337, + "pressure": 1 + }, + { + "x": 0.0771141341337576, + "y": 0.16406047881637825, + "pressure": 1 + }, + { + "x": 0.055103786521348896, + "y": 0.17216955367917242, + "pressure": 1 + }, + { + "x": 0.049311589781241345, + "y": 0.17680331074362624, + "pressure": 1 + }, + { + "x": 0.04004407499706925, + "y": 0.17680331074362624, + "pressure": 1 + }, + { + "x": 0.0342518782569617, + "y": 0.17332799294528586, + "pressure": 1 + }, + { + "x": 0.03541031760498321, + "y": 0.1536345254213572, + "pressure": 1 + }, + { + "x": 0.05278690782530587, + "y": 0.1362579364296554, + "pressure": 1 + }, + { + "x": 0.062054422609477966, + "y": 0.13509949716354194, + "pressure": 1 + }, + { + "x": 0.06437130130552099, + "y": 0.13162417936520157, + "pressure": 1 + }, + { + "x": 0.08058945217782214, + "y": 0.12583198303463433, + "pressure": 1 + }, + { + "x": 0.08174789152584365, + "y": 0.12235666523629396, + "pressure": 1 + }, + { + "x": 0.10028292109418782, + "y": 0.1142475903734998, + "pressure": 1 + }, + { + "x": 0.10375823913825236, + "y": 0.10961383330904599, + "pressure": 1 + }, + { + "x": 0.1199763900105535, + "y": 0.09918787991402492, + "pressure": 1 + }, + { + "x": 0.17789835741162904, + "y": 0.08412816945455003, + "pressure": 1 + } + ] + }, + { + "id": "e43a3399-0276-46f1-a29d-2b80b0aec786", + "layer_id": "670b1740-84e4-43f3-8bb2-0d3a96d42e4d", + "type": "brush_stroke", + "operation": "add", + "enabled": true, + "authoring": { + "name": "Brush Arc", + "visible": true, + "locked": false + }, + "size": 0.06, + "hardness": 0.65, + "opacity": 0.8, + "shape": "round", + "pressure_mode": "constant", + "points": [ + { + "x": 0.5567080242146631, + "y": 0.0458996736728061, + "pressure": 1 + }, + { + "x": 0.6412740966202334, + "y": 0.04474123440669264, + "pressure": 1 + }, + { + "x": 0.7165726542416316, + "y": 0.05980094486616753, + "pressure": 1 + }, + { + "x": 0.7293154870698683, + "y": 0.0679100197289617, + "pressure": 1 + }, + { + "x": 0.7675439855545781, + "y": 0.08412816945455003, + "pressure": 1 + }, + { + "x": 0.7999802872991804, + "y": 0.10613851551070563, + "pressure": 1 + }, + { + "x": 0.8266243923036751, + "y": 0.13278261863131505, + "pressure": 1 + }, + { + "x": 0.8358919070878472, + "y": 0.14900076835690337, + "pressure": 1 + }, + { + "x": 0.8416841038279548, + "y": 0.15479296468747064, + "pressure": 1 + }, + { + "x": 0.864852890788385, + "y": 0.1756448714775128, + "pressure": 1 + }, + { + "x": 0.8764372842686001, + "y": 0.18143706780808005, + "pressure": 1 + }, + { + "x": 0.8810710416606862, + "y": 0.18838770340476077, + "pressure": 1 + }, + { + "x": 0.8961307531849658, + "y": 0.19997209606589528, + "pressure": 1 + }, + { + "x": 0.9077151466651809, + "y": 0.2022889745981222, + "pressure": 1 + }, + { + "x": 0.9111904647092455, + "y": 0.206922731662576, + "pressure": 1 + }, + { + "x": 0.919299540145396, + "y": 0.20808117092868944, + "pressure": 1 + }, + { + "x": 0.9274086155815466, + "y": 0.21271492799314326, + "pressure": 1 + }, + { + "x": 0.9517358418899983, + "y": 0.21503180652537016, + "pressure": 1 + }, + { + "x": 0.9656371140662564, + "y": 0.21271492799314326, + "pressure": 1 + }, + { + "x": 0.9679539927622994, + "y": 0.20344741386423565, + "pressure": 1 + }, + { + "x": 0.9644786747182349, + "y": 0.19765521753366838, + "pressure": 1 + }, + { + "x": 0.9621617960221919, + "y": 0.16174360028415136, + "pressure": 1 + }, + { + "x": 0.9459436451498908, + "y": 0.15015920762301682, + "pressure": 1 + }, + { + "x": 0.9378345697137402, + "y": 0.13741637569576884, + "pressure": 1 + }, + { + "x": 0.9250917368855036, + "y": 0.12699042230074778, + "pressure": 1 + }, + { + "x": 0.919299540145396, + "y": 0.1188813474379536, + "pressure": 1 + }, + { + "x": 0.9135073434052885, + "y": 0.1165644689057267, + "pressure": 1 + }, + { + "x": 0.9065567073171594, + "y": 0.10613851551070563, + "pressure": 1 + }, + { + "x": 0.8764372842686001, + "y": 0.07601909459175586, + "pressure": 1 + }, + { + "x": 0.8636944514403635, + "y": 0.0679100197289617, + "pressure": 1 + }, + { + "x": 0.8521100579601484, + "y": 0.05632562706782717, + "pressure": 1 + }, + { + "x": 0.8382087857838902, + "y": 0.05285030926948681, + "pressure": 1 + }, + { + "x": 0.8277828316516966, + "y": 0.043582795140579195, + "pressure": 1 + }, + { + "x": 0.7710193035986426, + "y": 0.015780252753856333, + "pressure": 1 + }, + { + "x": 0.7698608642506211, + "y": 0.013463374221629427, + "pressure": 1 + }, + { + "x": 0.7501673953342555, + "y": 0.008829617157175618, + "pressure": 1 + } + ] + }, + { + "id": "a9648b4b-0c8b-4114-93db-e9c9b8c8fd79", + "layer_id": "670b1740-84e4-43f3-8bb2-0d3a96d42e4d", + "type": "brush_stroke", + "operation": "add", + "enabled": true, + "authoring": { + "name": "Brush Arc", + "visible": true, + "locked": false + }, + "size": 0.06, + "hardness": 0.65, + "opacity": 0.8, + "shape": "round", + "pressure_mode": "constant", + "points": [ + { + "x": 0.3041682463459737, + "y": 0.009988056423289069, + "pressure": 1 + }, + { + "x": 0.2740488232974145, + "y": 0.0238893276166505, + "pressure": 1 + }, + { + "x": 0.2543553543810488, + "y": 0.03779059881001193, + "pressure": 1 + }, + { + "x": 0.2033840230681023, + "y": 0.0458996736728061, + "pressure": 1 + }, + { + "x": 0.16399708523537093, + "y": 0.05980094486616753, + "pressure": 1 + }, + { + "x": 0.13735298023087616, + "y": 0.0725437767934155, + "pressure": 1 + }, + { + "x": 0.10723355718231689, + "y": 0.0922372443173442, + "pressure": 1 + }, + { + "x": 0.09680760305012329, + "y": 0.0945541228495711, + "pressure": 1 + }, + { + "x": 0.07479725543771458, + "y": 0.10845539404293253, + "pressure": 1 + }, + { + "x": 0.06668818000156401, + "y": 0.12003978670406706, + "pressure": 1 + }, + { + "x": 0.060895983261456454, + "y": 0.12003978670406706, + "pressure": 1 + } + ] + } + ], + "authoring": { + "visible": true, + "locked": false, + "color": "#54A24B" + } + } + ], + "schema": "bv.regional", + "title": "Regional Showcase - Android Dance", + "version": 1 +} \ No newline at end of file diff --git a/docs/prompt-ast-guide.md b/docs/prompt-ast-guide.md new file mode 100644 index 0000000..a9643f2 --- /dev/null +++ b/docs/prompt-ast-guide.md @@ -0,0 +1,72 @@ +# BV Prompt AST Guide + +BV Prompt AST stores prompt intent as structured blocks instead of repeatedly +parsing ad-hoc strings. The encoder emits both `BV_AST` and cleaned plain text; +downstream nodes can filter categories without losing the original hierarchy. + +## Syntax + +Unmarked text belongs to the default category: + +```text +A beautiful landscape, sunset lighting +``` + +Block categories remain active until the next block marker: + +```text +@@style +cinematic lighting +@@subject +a woman in rain +``` + +Inline categories delimit a smaller fragment: + +```text +a portrait with @ green eyes @@ and @ black hair @@ +``` + +Inline categories may be nested: + +```text +@ a @ smiling woman @@ in rain @@ +``` + +Comments are removed while their line break is retained: + +```text +a portrait ## authoring note, not part of the prompt +``` + +## Rules and failure cases + +- Category names match `[a-zA-Z0-9_-]+`; spaces are not allowed. +- Every inline category must be closed with `@@`. +- An unmatched closing marker or unclosed category raises an error with line and column. + +Invalid: + +```text +@ white dress @@ +@ long dress,@@@@ +``` + +Valid: + +```text +@ white dress @@ +@ long dress,@@ +``` + +## Typical chain + +1. **BV Prompt Encode** parses source text into `BV_AST`. +2. **BV Prompt Category Switch** enables or disables categories. +3. **BV Prompt Decode** materializes the selected plain prompt. +4. **BV Prompt AST Debug** exposes the current tree during authoring. + +[![Prompt AST workflow](../examples/images/prompt-ast-categories.png)](../examples/images/prompt-ast-categories.png) + +The workflow PNG contains importable ComfyUI metadata. A JSON fallback is +available at [`examples/workflows/prompt-ast-categories.json`](../examples/workflows/prompt-ast-categories.json). diff --git a/docs/regional-editor-guide.md b/docs/regional-editor-guide.md new file mode 100644 index 0000000..7fa3379 --- /dev/null +++ b/docs/regional-editor-guide.md @@ -0,0 +1,231 @@ +# BV Regional Editor Guide + +The BV Regional Editor authors a model-neutral `BV_REGIONAL` document. Geometry, +prompts and authoring metadata are stored once; model-specific compiler nodes +decide how much of that contract a backend can execute. + +[![Anima regional result](../examples/images/anima-android-dance-regional-showcase.png)](../examples/images/anima-android-dance-regional-showcase.png) + +The reference document behind this image uses two rectangle layers per character: +a main body area and a smaller shared interaction area. A third, painted region +guides the golden light arc. + +[Import the workflow PNG](../examples/images/anima-android-dance-regional-showcase.png) +Β· [Import the regional document](examples/anima-android-dance-regional-showcase.bv-regional.json) + +## Minimal workflow + +1. Add **BV Regional Prompt**. +2. Open the editor from the node or the BV toolbar action. +3. Define Global and Background prompts. +4. Add named regions and create rectangle or brush geometry. +5. Connect `regional` to a supported compiler. +6. Connect the compiler outputs to a standard KSampler. + +| Backend | Connect | Behavior | +| --- | --- | --- | +| Native/Krea-style | `BV Regional Native Conditioning` | Standard ComfyUI masked conditioning; no model attention patch | +| Anima | `BV Regional Anima Conditioning` | Built-in Anima attention patch; standard KSampler | +| External Anima fallback | `BV Regional Anima Adapter` | Compiles for the optional Sen-sou node pack | + +## Editor layout + +| Area | Purpose | +| --- | --- | +| Left panel | Regions, priority order, geometry layers, visibility, lock and selection | +| Artboard | WYSIWYG canvas, background preview, masks, selection handles, zoom and pan | +| Right panel | Region strength, feather, prompts and document prompts | +| Top menu | Import/export, undo/redo, display controls, canvas settings, completion data and help | +| Floating tool strip | Select, rectangle, additive brush and subtractive brush | + +Panel widths, open sections, active selection, zoom/pan and window geometry are +saved separately per `document_id`. They never alter the semantic regional document. + +
+Workspace and floating layouts + +![Regional Editor in workspace mode](assets/regional/editor-workspace.png) + +![Regional Editor in floating mode](assets/regional/editor-floating.png) + +Floating mode remains at viewport scale while the graph is zoomed or panned. + +
+ +
+Node and toolbar entry points + +![BV Regional Prompt node](assets/regional/regional-prompt-node.png) + +![BV toolbar actions](assets/regional/toolbar-actions.png) + +![Open Regional Editor action](assets/regional/toolbar-editor-hover.png) + +![Quick Edit action](assets/regional/toolbar-quick-hover.png) + +
+ +## Geometry and layers + +- Rectangles show a live preview while dragging and support move plus eight resize handles. +- Brush layers support round/square tips, size, hardness, opacity and optional stylus pressure. +- Subtractive brush strokes remove from the selected brush layer; they do not create white masks. +- Regions and layers can be renamed, reordered, locked, hidden, disabled, duplicated or deleted. +- Regions may overlap. Version 1 executes the overlap mode `joint`. +- Canvas width and height control the authoring aspect ratio even when no background exists. + +Mask overlay opacity and background-image opacity are display-only settings. They +do not change exported masks, regional strength or the image returned by a sender. + +
+Display controls + +![Mask and background-image opacity controls](assets/regional/view-controls.png) + +
+ +
+Reference document geometry + +The main layers guide the two character designs. The smaller rectangles overlap +where their hands should meet, while the brush region demonstrates freehand geometry. + +![Cyan main body](assets/regional/region-cyan-main.png) + +![Cyan interaction area](assets/regional/region-cyan-interaction.png) + +![Amber main body](assets/regional/region-amber-main.png) + +![Amber interaction area](assets/regional/region-amber-interaction.png) + +![Holographic light arc brush](assets/regional/region-brush-arc.png) + +
+ +## Prompts + +Each document contains: + +- Global positive and negative prompts; +- Background positive and negative prompts; +- positive and negative prompts per region; +- per-region strength and feather; +- negative mode, including the technical zero-out path. + +Global prompting establishes composition and concepts across the image. Regional +prompts should usually describe local attributes rather than duplicate the entire +scene. A region guides where conditioning applies; it is not a hard object boundary. + +## How strict is regional guidance? + +Regional prompting and attention masking bias where prompt information is available; +they do not clip a generated object to a mask. Results still depend on the model, +seed, sampler, prompt composition, mask geometry and backend implementation. + +- A subject may extend beyond its region or appear slightly offset from it. +- Attributes may bleed between nearby or strongly overlapping regions. +- A small interaction region can make both regional contexts available around a + contact point, but it cannot guarantee joined hands, eye contact or another pose. +- Region strength controls conditioning influence. Raising it does not turn the + region into a stricter bounding box and can overemphasize local concepts. +- Global prompts can still influence composition and placement across the full image. + +Treat masks as spatial intent. Validate important layouts across several seeds and +adjust geometry, prompt wording and backend settings together. + +## Workspace, floating and Quick Edit + +Workspace mode fills the available browser viewport. Floating mode is independently +movable and resizable and remains unaffected by graph zoom or pan. + +Quick Edit changes Global, Background or one selected region without opening the +full artboard. It targets stable document and region IDs even though the UI shows names. + +
+Quick Edit over a live workflow + +![Regional Quick Edit](assets/regional/quick-edit.png) + +
+ +## Background feedback + +- **BV Regional Preview Send** returns a temporary preview to a selected editor. +- **BV Regional Save Send** saves normally and returns the saved result. +- Multiple senders use last-completed-sender-wins semantics. +- Images are not embedded as Base64 in the workflow document. + +This makes it possible to redraw masks over the latest sampler, detailer or upscale +result without creating a workflow cycle. + +## Prompt autocomplete + +BV Prompt Autocomplete works in the full editor, Quick Edit and ordinary ComfyUI +multiline widgets. Tags from the default dataset are inserted with spaces while the +canonical underscore form remains available as metadata. + +Autocomplete is optional. Disable it under **Settings β†’ BV Node Pack β†’ Prompting** +or from **Edit β†’ Prompt Autocomplete** when another extension should own prompt fields. +Several CSV/TSV datasets may be enabled and ordered; the topmost source wins duplicate tags. + +
+Completion surfaces + +![Autocomplete in Quick Edit](assets/regional/autocomplete-quick-edit.png) + +![Autocomplete in the full editor](assets/regional/autocomplete-editor.png) + +![Autocomplete in a native multiline widget](assets/regional/autocomplete-multiline.png) + +
+ +
+Dataset settings and priority + +![Completion dataset settings](assets/regional/completion-settings.png) + +
+ +## Document tools + +| Node | Use | +| --- | --- | +| BV Regional Debug | Canonical JSON, summary and stable `document_id` | +| BV Regional Select | Select Global, Background or a named region | +| BV Regional Deconstructor | AST, plain text, source text and reusable selection | +| BV Regional Prompt Extract | Extract positive/negative AST and text | +| BV Regional Mask Render | Render mask plus pixel bounding box | + +These seams are intended for later detailer adapters and other consumers without +coupling them to the editor UI. + +## Anima reference workflow + +The built-in Anima path has been verified with two independently conditioned +characters, joint interaction overlap, a painted light region and a standard KSampler. + +
+Minimal workflow + +![Anima regional workflow](assets/regional/anima-workflow.png) + +
+ +Import either the metadata-bearing +[`workflow PNG`](../examples/images/anima-android-dance-regional-showcase.png) +or the editor-only +[`regional document`](examples/anima-android-dance-regional-showcase.bv-regional.json). + +## Current limits + +- `joint` is the only executable overlap mode; normalized, exclusive and priority modes are reserved. +- Native masked conditioning does not provide model-internal attention isolation. +- The built-in attention backend currently targets Anima; other model families require future adapters. +- Parent-region IDs exist in the schema, but hierarchy authoring is not exposed yet. +- Regional negative isolation depends on backend capability. +- A region is conditioning guidance, not a guaranteed object-sized bounding box, + exact pose constraint or pixel-perfect interaction target. + +For the formal schema and implementation boundaries, see +[`docs/specs/bv-regional-v1.md`](specs/bv-regional-v1.md) and +[`docs/regional-editor-mvp.md`](regional-editor-mvp.md). diff --git a/docs/regional-editor-mvp.md b/docs/regional-editor-mvp.md index 1b962d8..0ad86e2 100644 --- a/docs/regional-editor-mvp.md +++ b/docs/regional-editor-mvp.md @@ -21,7 +21,6 @@ In Version 1 ist nur die Overlap-Semantik `joint` ausfΓΌhrbar. Die reservierten - `BV Regional Preview Send` (interne kompatible Klassenkennung `BV Regional Image Send`): sendet ein temporΓ€res Preview-Ergebnis an den Editor eines ausgewΓ€hlten `BV Regional Prompt`. Die sichtbare Auswahl verwendet Node-Titel und Node-ID, wΓ€hrend intern die stabile `document_id` gespeichert wird. Bei mehreren ausgefΓΌhrten Sendern gewinnt das zuletzt beim Frontend eingetroffene Ergebnis; entfernte Ziele werden nicht stillschweigend auf ein anderes Dokument umgebogen. - `BV Regional Save Send` (interne Klassenkennung `BV Regional Image Save`): speichert das Bild regulΓ€r im ComfyUI-Output, sendet dasselbe gespeicherte Ergebnis an den ausgewΓ€hlten Editor und reicht das Bild am Ausgang weiter. ZielauflΓΆsung und Last-Sender-Wins-Semantik entsprechen der Preview-Variante. Das modellbezogene Backend wird erst beim AusfΓΌhren dieser Node importiert. Fehlende optionale AbhΓ€ngigkeiten oder inkompatible ComfyUI-Patcher-Schnittstellen dΓΌrfen deshalb nicht die Registrierung des ΓΌbrigen BV NodePacks verhindern. -- `BV Regional Image Send`: IMAGE-Passthrough, das eine temporΓ€re Preview an eine `document_id` sendet. Pro Dokument gewinnt die zuletzt ausgefΓΌhrte Sender-Node. ## Editor-Verhalten @@ -75,23 +74,23 @@ Geometrieebenen besitzen dafΓΌr rΓΌckwΓ€rtskompatible optionale Felder `enabled` ## Hintergrundbilder -`BV Regional Image Send` speichert ausschließlich eine ComfyUI-Temp-Preview. Die Browser-Session ordnet das letzte Ergebnis anhand der `document_id` zu. Das Bild wird nicht in `BV_REGIONAL` und nicht als Base64 im Workflow persistiert. Ein Workflow-Reload beginnt daher absichtlich ohne Sender-Hintergrund, bis die Sender-Node erneut ausgefΓΌhrt wird. +`BV Regional Preview Send` speichert ausschließlich eine ComfyUI-Temp-Preview. Die Browser-Session ordnet das letzte Ergebnis anhand der `document_id` zu. Das Bild wird nicht in `BV_REGIONAL` und nicht als Base64 im Workflow persistiert. Ein Workflow-Reload beginnt daher absichtlich ohne Sender-Hintergrund, bis die Sender-Node erneut ausgefΓΌhrt wird. -## Geplante Editor-Erweiterungen +## Prompt-Bearbeitung und Completion ### Prompt-Schnellbearbeitung -Ohne den vollstΓ€ndigen Editor zu ΓΆffnen, soll eine kompakte Prompt-Palette erreichbar sein. Sie bietet direkte Ziele fΓΌr Global, Background und jede Region und zeigt jeweils Positive und Negative als editierbare Textfelder. Die Zielauswahl verwendet sichtbare Namen, speichert intern jedoch stabile IDs. Γ„nderungen laufen durch dieselbe Validierungs-, AST- und Undo-Pipeline wie Γ„nderungen im vollstΓ€ndigen Editor; es entsteht keine zweite Prompt-Datenquelle. +Ohne den vollstΓ€ndigen Editor zu ΓΆffnen, ist eine kompakte Prompt-Palette erreichbar. Sie bietet direkte Ziele fΓΌr Global, Background und jede Region und zeigt jeweils Positive und Negative als editierbare Textfelder. Die Zielauswahl verwendet sichtbare Namen, speichert intern jedoch stabile IDs. Γ„nderungen laufen durch dieselbe Validierungs- und Dokumentpipeline wie Γ„nderungen im vollstΓ€ndigen Editor; es entsteht keine zweite Prompt-Datenquelle. -Die Schnellbearbeitung soll sowohl ΓΌber die jeweilige `BV Regional Prompt`-Node als auch ΓΌber die globale Action-Bar-OberflΓ€che fΓΌr das aktuell gewΓ€hlte Dokument erreichbar sein. Bei mehreren Editor-Nodes muss vor dem Bearbeiten eindeutig sichtbar sein, welches Dokument aktiv ist. +Die Schnellbearbeitung ist sowohl ΓΌber die jeweilige `BV Regional Prompt`-Node als auch ΓΌber die globale Action-Bar-OberflΓ€che erreichbar. Bei mehreren Editor-Nodes zeigt die Dokumentauswahl eindeutig, welches Dokument aktiv ist; das zuletzt gewΓ€hlte Prompt-Ziel wird pro Dokument gespeichert. ### AutovervollstΓ€ndigung und Textassistenz -Die Promptfelder verwenden `BV Global Completion`, ein nodepack-weites Completion-Modul mit austauschbarer Suggestion-Provider-Schnittstelle. Dieselbe Engine integriert neben BV React-Editoren auch geeignete klassische ComfyUI- und Nodes-2.0-Multiline-Widgets, sodass Benutzer kein zweites Completion-System benΓΆtigen. Details und IntegrationsvertrΓ€ge stehen in `docs/specs/bv-global-completion.md`. +Die Promptfelder verwenden `BV Global Completion`, ein nodepack-weites Completion-Modul mit austauschbarer Suggestion-Provider-Schnittstelle. Dieselbe Engine integriert neben BV React-Editoren auch geeignete klassische ComfyUI- und Nodes-2.0-Multiline-Widgets. Sie verwendet lokale CSV-/TSV-Datasets, unterstΓΌtzt priorisierte Quellen und kann global oder im Editor deaktiviert werden. Details und IntegrationsvertrΓ€ge stehen in `docs/specs/bv-global-completion.md`. `comfy-ex-tagcomplete` und vergleichbare Widget-Extensions kΓΆnnen abgekoppelte React-/Floating-Textfelder nicht ΓΌber einen gemeinsamen stabilen nativen Opt-in-Hook registrieren. BV emuliert deshalb weder Node-DOM noch importiert es private Frontendklassen fremder Extensions. Normale `