dsh-multimodal-node 0.0.0-stage → 0.2.2

package/lib/library.js

@@ -0,0 +1,1209 @@
+/**
+ * The gateway's own workflow library.
+ *
+ * ComfyUI 0.3.77 does not expose a user workflow directory on every install
+ * (`/userdata?dir=workflows` answers 404 until the frontend saves something),
+ * so the remote console cannot rely on reading the instance's files. The
+ * library therefore lives here, in the plugin data directory, in one JSON file:
+ *
+ *   { id, name, kind, graph, api, targets, updatedAt, nodeCount }
+ *
+ * `graph` is what the person edited (UI graph or API map), `api` is the converted
+ * prompt cached at save time and re-converted on demand if the instance learned
+ * new nodes. Keeping both means an edit is cheap and a broken conversion is
+ * visible immediately instead of at generation time.
+ */
+import { mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { graphToApi, imageTargets, promptTargets } from './workflows.js';
+import { classifyWorkflow, visibleTo } from './tiers.js';
+
+export class WorkflowLibrary {
+    constructor(dataDir) {
+        this.file = join(dataDir, 'workflows.json');
+        this.items = [];
+        /** `mtimeMs:size` of the file this.items was read from; see reloadIfChanged. */
+        this.stamp = undefined;
+    }
+
+    async init() {
+        await mkdir(join(this.file, '..'), { recursive: true });
+        try {
+            const raw = await readFile(this.file, 'utf8');
+            const parsed = JSON.parse(raw);
+            this.items = Array.isArray(parsed) ? parsed : [];
+        } catch {
+            this.items = [];
+            await this.save();
+        }
+        // Record what was read, so reloadIfChanged() can tell "same file" from "a
+        // different file" without re-parsing on every render.
+        try {
+            const info = await stat(this.file);
+            this.stamp = `${info.mtimeMs}:${info.size}`;
+        } catch {
+            this.stamp = 'missing';
+        }
+    }
+
+    async save() {
+        const temp = `${this.file}.tmp`;
+        await writeFile(temp, `${JSON.stringify(this.items, null, 2)}\n`, 'utf8');
+        await rename(temp, this.file);
+        // Our own write must not look like an external change on the next read.
+        try {
+            const info = await stat(this.file);
+            this.stamp = `${info.mtimeMs}:${info.size}`;
+        } catch {
+            this.stamp = undefined;
+        }
+    }
+
+    /**
+     * The shared library as one tier sees it.
+     *
+     * No owner filter: every account browses the same list. What a workflow's `owner` still
+     * records is who created it (useful when auditing an import), not who may see it.
+     *
+     * A workflow the account may not see is omitted entirely rather than shown disabled —
+     * a greyed-out row still leaks the name, and "NSFW_xxx" as a title is the disclosure.
+     */
+    list(tier = 'sfw') {
+        return this.items
+            .filter((item) => visibleTo(tier, classifyWorkflow(item).tier))
+            .map((item) => ({
+                id: item.id,
+                name: item.name,
+                kind: item.kind ?? 'graph',
+                tier: classifyWorkflow(item).tier,
+                category: item.category ?? 't2i',
+                nodeCount: item.nodeCount ?? null,
+                updatedAt: item.updatedAt ?? null,
+                /** Provenance only; it does not gate anything any more. */
+                owner: item.owner ?? null,
+            }));
+    }
+
+    /** The library as the panel sees it: everything, with its classification. */
+    listAll() {
+        return this.items.map((item) => ({
+            id: item.id,
+            name: item.name,
+            kind: item.kind ?? 'graph',
+            tier: classifyWorkflow(item).tier,
+            reason: classifyWorkflow(item).reason,
+            nodeCount: item.nodeCount ?? null,
+            updatedAt: item.updatedAt ?? null,
+        }));
+    }
+
+    get(id) {
+        return this.items.find((item) => item.id === id);
+    }
+
+    /**
+     * Create or update one workflow.
+     * @param {{id?:string, name:string, graph:object, objectInfo?:object}} input
+     */
+    async put(input) {
+        const name = String(input.name ?? '').trim();
+        if (name === '') throw new Error('工作流需要名字');
+        const graph = input.graph;
+        if (graph === null || typeof graph !== 'object') throw new Error('工作流内容必须是 JSON 对象');
+        /**
+         * An API-format workflow is already the prompt; it must not be dragged through
+         * the UI→API converter.
+         *
+         * The converter needs `objectInfo` (the instance's node table), which a bulk
+         * import does not have. Feeding a graph that is *already* `{id: {class_type,
+         * inputs}}` to it with `objectInfo` absent used to leave `api = null`, and every
+         * downstream consequence followed from that: targets were never computed (so
+         * the console showed no prompt boxes on a text-to-image workflow) and
+         * nodeCount was null (so the picker could not say how big it is).
+         *
+         * Detection mirrors graphToApi's own test, so both agree on what "already API"
+         * means.
+         */
+        const looksApi =
+            !Array.isArray(graph.nodes) &&
+            Object.keys(graph).length > 0 &&
+            Object.values(graph).every((node) => node !== null && typeof node === 'object' && typeof node.class_type === 'string');
+        const conversion = looksApi
+            ? { prompt: graph, warnings: [] }
+            : input.objectInfo === undefined
+              ? { prompt: null, warnings: [] }
+              : graphToApi(graph, input.objectInfo);
+        if (conversion.prompt === null && input.objectInfo !== undefined && conversion.error !== undefined) {
+            throw new Error(`工作流无法转换：${conversion.error}`);
+        }
+        const api = conversion.prompt;
+        // Declared FIRST: everything below — targets, owner, heads, promptNodes — reads it,
+        // and a `const` referenced before its declaration line is a temporal-dead-zone throw
+        // ("Cannot access 'existing' before initialization"), not an undefined read.
+        const existing = input.id === undefined ? undefined : this.get(input.id);
+        const targets = api === null ? {} : {
+            texts: promptTargets(api, input.promptNodes ?? existing?.promptNodes ?? null),
+            images: imageTargets(api, input.objectInfo ?? {}),
+        };
+        // Ownership is what makes the remote console per-account: a workflow
+        // created from another person's session belongs to them and is invisible
+        // here. An update keeps the original owner even when someone else with
+        // permission edits it.
+        const owner = existing?.owner ?? (typeof input.owner === 'string' && input.owner !== '' ? input.owner : null);
+        /**
+         * Prompt heads are gone as a separate concept.
+         *
+         * The positive and negative prompt IS the encoder text in `api`, so there is no
+         * second place to store a prefix. The field is still accepted (an older client, or
+         * a script, may send it) but it is deliberately never applied at submit time —
+         * see the heads block in remote.js. Storing it at all would recreate the two-copy
+         * problem: JSON says one prompt, this says another, the picture uses whichever.
+         */
+        const heads = null;
+        /**
+         * Positive-prompt layers. Same "null means unchanged" rule as heads: a workflow
+         * that never had layers keeps none, and sending `[]` is how a person removes them.
+         *
+         * Kept as the FALLBACK for workflows written before per-node layers existed; see
+         * nodeLayers below.
+         */
+        const layers = normalizeLayers(input.layers) ?? existing?.layers ?? null;
+        /**
+         * Per-node prompt layers: {nodeId: [{name}, …]}.
+         *
+         * Each text node has its own list — a negative encoder wants 排除项 / 画质, not the
+         * positive's 面部 / 躯干. `{}` clears every per-node definition (and falls back to the
+         * workflow-level list above), which is how a person undoes the whole split.
+         */
+        const nodeLayers = normalizeNodeLayers(input.nodeLayers) ?? existing?.nodeLayers ?? null;
+        /**
+         * Extra parameters the operator pinned for this workflow.
+         *
+         * The derived list is a fixed whitelist (steps/cfg/seed/…); real graphs carry knobs
+         * outside it (ControlNet strength, LoRA weight, a second sampler). A pin names one
+         * node input and the console then offers it like any other parameter. Values still
+         * come from the graph, so a pin can never invent a value.
+         *
+         * Same null-means-unchanged rule as heads and layers, so `[]` is how a person
+         * removes the last pin.
+         */
+        const paramPicks = normalizeParamPicks(input.paramPicks) ?? existing?.paramPicks ?? null;
+        /**
+         * Derived parameters the operator un-associated.
+         *
+         * A stored list, unlike the derived rows themselves, because the removal has to
+         * survive a reopen: without it the row comes back on the next render and the delete
+         * button looks broken. It only affects what the FORM offers — the graph keeps the
+         * input, so the run still uses the body's value. Same null-means-unchanged rule.
+         */
+        const paramHidden = normalizeParamHidden(input.paramHidden) ?? existing?.paramHidden ?? null;
+        /**
+         * Which encoder is the positive one and which is the negative one, when the operator
+         * says so.
+         *
+         * Role used to be inferred: trace the sampler's `positive` / `negative` links, else
+         * look for "neg" in the name. That works for the two-encoder graphs everybody starts
+         * with and fails for the graphs that actually need it — a双 CLIP graph feeding one
+         * sampler, an SDXL pair, an extra refiner encoder — where several text nodes are all
+         * "positive" by wiring and the console then showed the same role twice. The operator
+         * knows which slot is which; this is where that answer is stored.
+         *
+         * Only the role is stored, never text: values stay in the graph.
+         */
+        const promptNodes = normalizePromptNodes(input.promptNodes) ?? existing?.promptNodes ?? null;
+        /**
+         * Which text node carries each head — see normalizeHeadNodes.
+         *
+         * Stored next to promptNodes and validated against it: the head declaration may only
+         * name a node the operator already assigned that role, so "节点 7 是正向" and "正向
+         * 表头在节点 7" cannot drift apart.
+         */
+        const headNodes = normalizeHeadNodes(input.headNodes, promptNodes) ?? existing?.headNodes ?? null;
+        /**
+         * Per-node heads — the shape the workbench writes now.
+         *
+         * `normalizeNodeHeads` returns null for "not provided", so `?? existing` keeps the
+         * stored map on an unrelated save; sending `{}` is how a person clears all of them.
+         * The map only carries nodes the operator overrode; everything else reads the graph.
+         */
+        const nodeHeads = normalizeNodeHeads(input.nodeHeads) ?? existing?.nodeHeads ?? null;
+        const record = {
+            id: existing?.id ?? `wf-${randomBytes(4).toString('hex')}`,
+            name,
+            owner,
+            declared: input.declared === 'nsfw' ? 'nsfw' : undefined,
+            /**
+             * What kind of workflow this is, as the operator classified it.
+             *
+             * Separate from the tier: the tier is a visibility ceiling, the category is
+             * what the thing makes (image / video / audio, from text or from an image).
+             * It is declared, not guessed — a graph's node types do not reliably say
+             * whether the operator means text-to-image or image-to-image.
+             */
+            category: normalizeCategory(input.category) ?? existing?.category ?? 't2i',
+            heads,
+            layers,
+            nodeLayers,
+            paramPicks,
+            paramHidden,
+            /**
+             * Which `nodeId::input` keys the instance declares BOOLEAN.
+             *
+             * Persisted because the run path has no node table: the console builds its form
+             * from the stored record, and a switch that is not known to be a switch renders as
+             * a text box and submits a string — the reported「开关参数提交时仍然按照字符串提交」.
+             *
+             * Recomputed on every save that brings an `objectInfo`; kept from the previous
+             * record otherwise, so an edit made offline does not erase it.
+             */
+            booleanKeys: (() => {
+                const fresh = booleanInputsOf(api, input.objectInfo);
+                if (fresh.size > 0) return [...fresh].sort();
+                const previous = existing?.booleanKeys;
+                return Array.isArray(previous) ? previous : [];
+            })(),
+            promptNodes,
+            headNodes,
+            nodeHeads,
+            kind: Array.isArray(graph.nodes) ? 'graph' : 'api',
+            graph,
+            api,
+            targets,
+            warnings: conversion.warnings ?? [],
+            nodeCount: api === null ? null : Object.keys(api).length,
+            updatedAt: new Date().toISOString(),
+        };
+        if (existing === undefined) {
+            this.items.push(record);
+        } else {
+            this.items[this.items.indexOf(existing)] = record;
+        }
+        await this.save();
+        return this.describe(record);
+    }
+
+    /**
+     * Adopt workflows that predate ownership.
+     *
+     * A library seeded before the console became per-account has rows with no
+     * owner. Leaving them ownerless would make them invisible to everyone (the
+     * per-account filter would drop them), which is a data loss in effect, so they
+     * are assigned to the machine's owner on first start.
+     */
+    async claimOwnerless(owner) {
+        let claimed = 0;
+        for (const item of this.items) {
+            if (item.owner === null || item.owner === undefined) {
+                item.owner = owner;
+                claimed += 1;
+            }
+        }
+        if (claimed > 0) await this.save();
+        return claimed;
+    }
+
+    /** Drop every workflow one account created (called when the account goes). */
+    async dropOwner(owner) {
+        const before = this.items.length;
+        this.items = this.items.filter((item) => item.owner !== owner);
+        if (this.items.length !== before) await this.save();
+        return { ok: true, removed: before - this.items.length };
+    }
+
+    async remove(id) {
+        const before = this.items.length;
+        this.items = this.items.filter((item) => item.id !== id);
+        if (this.items.length === before) throw new Error(`没有工作流 ${id}`);
+        await this.save();
+        return { ok: true };
+    }
+
+    /**
+     * Re-read workflows.json from disk.
+     *
+     * The library is loaded once at startup, so anything that writes the file while
+     * the plugin is running (an import script, a bulk edit, a hand fix) is invisible
+     * to the console until the whole host restarts — and "Restart gateway" only
+     * restarts the listeners, it does not re-read state. That gap is what made ten
+     * freshly imported workflows show up on disk and nowhere in the UI.
+     *
+     * On-demand rather than a file watcher: the console already calls list() on every
+     * render, a stat() is far cheaper than an fs.watch registration per file, and it
+     * cannot miss a change that happened before the watcher attached.
+     */
+    async reloadIfChanged() {
+        let stamp;
+        try {
+            const info = await stat(this.file);
+            stamp = `${info.mtimeMs}:${info.size}`;
+        } catch {
+            // A missing file means an empty library, not an error to surface.
+            if (this.stamp !== 'missing') {
+                this.items = [];
+                this.stamp = 'missing';
+                return { reloaded: true, rows: 0 };
+            }
+            return { reloaded: false, rows: 0 };
+        }
+        if (this.stamp === stamp) return { reloaded: false, rows: this.items.length };
+        await this.init();
+        this.stamp = stamp;
+        return { reloaded: true, rows: this.items.length };
+    }
+
+    /**
+     * Build the runnable prompt for one workflow, applying the console's text and
+     * image edits, and re-converting when the cached API form is missing.
+     */
+    resolve(id, objectInfo) {
+        const record = this.get(id);
+        if (record === undefined) throw new Error(`没有工作流 ${id}`);
+        let api = record.api;
+        const warnings = [...(record.warnings ?? [])];
+        if (api === null || api === undefined) {
+            const converted = graphToApi(record.graph, objectInfo ?? {});
+            if (converted.prompt === null) throw new Error(converted.error ?? '工作流无法转换成 API 格式');
+            api = converted.prompt;
+            warnings.push(...converted.warnings);
+        }
+        return { record, api: structuredClone(api), warnings };
+    }
+
+    describe(record) {
+        const api = record.api;
+        // Recomputed on read rather than trusted from the saved record: target
+        // detection is pure and cheap, and a saved `targets` block would keep an
+        // older, wrong classification alive after a fix.
+        const classification = classifyWorkflow(record);
+        /**
+         * Roles stay as declared; the head declaration is reported separately.
+         *
+         * They answer different questions and must not be merged: `promptNodes` says "which
+         * nodes are positive / negative", `headNodes` says "which ONE of them the console's
+         * head box belongs to". Collapsing the second into the first would relabel the other
+         * positives as negatives on a two-encoder graph.
+         */
+        const promptNodes = normalizePromptNodes(record.promptNodes) ?? null;
+        const texts = api === null || api === undefined
+            ? (record.targets?.texts ?? [])
+            : promptTargets(api, promptNodes);
+        /**
+         * One entry per text node the console will actually show a box for.
+         *
+         * This is the console's whole prompt surface: a node the operator marked 不参与 is
+         * absent, and when every node is marked that way the list is empty — the console then
+         * renders nothing, which is the requested behaviour and cannot be expressed by
+         * `needsText` alone.
+         */
+        const boxes = promptBoxes(texts, record.nodeHeads ?? null, record.nodeLayers ?? null, record.layers ?? null);
+        return {
+            id: record.id,
+            name: record.name,
+            kind: record.kind,
+            owner: record.owner ?? null,
+            /**
+             * Whether this graph has anything to type into. A pure upscale, a
+             * face swap or an interpolation has no text node, so the console must
+             * hide its prompt section rather than show two empty boxes nobody can
+             * meaningfully fill. Marking every text node 不参与 is the same answer:
+             * no box, because a box nobody reads is worse than no box.
+             */
+            needsText: boxes.length > 0,
+            /**
+             * Per-node prompt surface: [{nodeId, input, role, classType, head, value, layers}].
+             *
+             * `layers` on each box is THAT node's own layering, empty when it has none — the
+             * console draws one layer input per entry under that box, so a negative encoder
+             * can have 排除项 / 画质 while the positive has 面部 / 躯干.
+             */
+            promptBoxes: boxes,
+            /** What it makes: t2i / i2i / t2v / i2v / t2a. */
+            category: record.category ?? 't2i',
+            heads: record.heads ?? null,
+            /**
+             * The workflow-level layer list, kept as the legacy fallback.
+             *
+             * Per-node layers live on each `promptBoxes` entry; this is what a workflow
+             * written before that change still carries, and `layersForNode` applies it to the
+             * node that has no entry of its own.
+             */
+            layers: Array.isArray(record.layers) ? record.layers : [],
+            /** Per-node layer definitions: {nodeId: [{name}]}. Null = none. */
+            nodeLayers: normalizeNodeLayers(record.nodeLayers) ?? null,
+            /** Extra parameters this workflow exposes beyond the derived whitelist. */
+            paramPicks: Array.isArray(record.paramPicks) ? record.paramPicks : [],
+            paramHidden: Array.isArray(record.paramHidden) ? record.paramHidden : [],
+            /** Operator-declared positive/negative encoder ids, or null when inferred. */
+            promptNodes,
+            /** Per-node head overrides: {nodeId: {input, value}}. Null = none. */
+            nodeHeads: normalizeNodeHeads(record.nodeHeads) ?? null,
+            /**
+             * Which text node carries each head, or null when it is "the first one with that
+             * role". The legacy per-role view; the console reads `promptBoxes` instead.
+             */
+            headNodes: normalizeHeadNodes(record.headNodes, promptNodes) ?? null,
+            /** Node titles, so the parameter list can be grouped by node NAME, not just id. */
+            nodeTitles: collectNodeTitles(record.graph, api),
+            /**
+             * Which node each head box addresses, resolved (legacy per-role view).
+             *
+             * The console sends per-run text with `{nodeId, input}` taken from here, so the
+             * box shown and the encoder written are the same node by construction — the
+             * declaration cannot be honoured by one and ignored by the other.
+             */
+            headTargets: headTargets(texts, record.headNodes ?? null),
+            tier: classification.tier,
+            tierReason: classification.reason,
+            nodeCount: record.nodeCount,
+            updatedAt: record.updatedAt,
+            warnings: record.warnings ?? [],
+            texts,
+            /**
+             * Image slots, RECOMPUTED on every read — never trusted from the record.
+             *
+             * This line used to be `record.targets?.images ?? []`, a snapshot taken when the
+             * workflow was saved. That made every improvement to the detector invisible on
+             * existing workflows: 去除衣物 kept reporting zero image inputs long after the
+             * annotation-stripping fix, because its stored snapshot was still the empty list
+             * computed by the old code. Detection is pure and cheap; recomputing is what makes
+             * a fix reach the workflows already in the library.
+             *
+             * `record.images` (an operator override) is honoured first if present, so an
+             * explicit declaration still wins over inference.
+             */
+            images: Array.isArray(record.images)
+                ? record.images
+                : (api === null || api === undefined ? (record.targets?.images ?? []) : imageTargets(api, record.objectInfo ?? {})),
+            nodes: api === null || api === undefined ? [] : Object.entries(api).map(([nodeId, node]) => ({
+                nodeId,
+                classType: node.class_type,
+                inputs: Object.keys(node.inputs ?? {}),
+            })),
+        };
+    }
+}
+
+/** The five categories a workflow can belong to. */
+export const CATEGORIES = [
+    { id: 't2i', label: '文生图' },
+    { id: 'i2i', label: '图生图' },
+    { id: 't2v', label: '文生视频' },
+    { id: 'i2v', label: '图生视频' },
+    { id: 't2a', label: '文生音频' },
+];
+
+const CATEGORY_IDS = new Set(CATEGORIES.map((entry) => entry.id));
+
+/** Accept a category id, or null when the caller said nothing usable. */
+export function normalizeCategory(value) {
+    const id = String(value ?? '').trim();
+    return CATEGORY_IDS.has(id) ? id : null;
+}
+
+/**
+ * One key parameter, as the operator declares it.
+ *
+ * Four fields, fixed, everywhere: the editor, the console, the API and storage all speak
+ * this shape. A parameter is a *named handle* on a node input, not the input itself —
+ * `nodeId` + `input` locate it, `name` is what the person sees, `value` is the default the
+ * console starts from, and `desc` explains what turning it does.
+ */
+export const MAX_PARAM_PICKS = 40;
+
+/** The canonical field list, exported so the UI and the parser cannot drift apart. */
+export const PARAM_FIELDS = ['name', 'nodeId', 'value', 'desc'];
+
+/**
+ * Which inputs on this graph are BOOLEAN, according to the instance's own node table.
+ *
+ * This is the authority for "is this a switch", and it had to come from somewhere: the stored
+ * graph holds `"true"` as a STRING (ComfyUI itself accepts that for these custom nodes), so
+ * deciding by `typeof value === 'boolean'` never fired and every real switch rendered as a
+ * plain text value. `object_info` says `["BOOLEAN", {...}]` for the same input, and that is
+ * the fact that actually governs what the instance will accept.
+ *
+ * Returns a Set of `nodeId::input` keys. An unknown class contributes nothing, so a graph
+ * referencing a node type this instance lacks stays fallible rather than guessed at.
+ */
+export function booleanInputsOf(api, objectInfo) {
+    const out = new Set();
+    if (objectInfo === null || typeof objectInfo !== 'object') return out;
+    for (const [nodeId, node] of Object.entries(api ?? {})) {
+        const spec = objectInfo[node?.class_type];
+        if (spec === undefined) continue;
+        for (const bucket of [spec.input?.required, spec.input?.optional]) {
+            if (bucket === null || typeof bucket !== 'object') continue;
+            for (const [input, decl] of Object.entries(bucket)) {
+                const type = Array.isArray(decl) ? decl[0] : decl?.type;
+                if (String(type).toUpperCase() !== 'BOOLEAN') continue;
+                out.add(`${nodeId}::${input}`);
+            }
+        }
+    }
+    return out;
+}
+
+/**
+ * Accept a list of declared parameters, de-duplicated by node+input.
+ *
+ * `null` means "unchanged"; `[]` means "clear them". The older stored shape was just
+ * `{nodeId, input}`, so an entry without `name` is accepted and named after its input —
+ * otherwise every workflow written before this change would lose its parameters.
+ */
+
+/**
+ * Accept a list of declared parameters, de-duplicated by node+input.
+ *
+ * `null` means "unchanged"; `[]` means "clear them". The older stored shape was just
+ * `{nodeId, input}`, so an entry without `name` is accepted and named after its input —
+ * otherwise every workflow written before this change would lose its parameters.
+ */
+/**
+ * Resolve one parameter row's kind, keeping the four-way distinction.
+ *
+ * Seed wins over everything: it is decided by the input name, and a seed the operator
+ * mislabelled as a model would render a file picker for a number. Then an explicit
+ * declaration — "model", "seed" or "switch" — then plain value.
+ *
+ * `switch` is the fourth kind, and it is not a number with two values: ComfyUI validates a
+ * BOOLEAN input against the JSON type, so writing "true" (a string) or 1 instead of `true`
+ * gets the prompt rejected after it has already been queued. The console therefore renders
+ * it as a true/false picker and the server writes a real boolean.
+ */
+export function normalizeParamKind(entry, input, isBoolean = false) {
+    const name = String(input ?? entry?.input ?? '');
+    if (/^(?:seed|noise_seed|rand_seed|random_seed)$/i.test(name)) return 'seed';
+    const declared = String(entry?.kind ?? '');
+    if (declared === 'model') return 'model';
+    if (declared === 'seed') return 'seed';
+    if (declared === 'switch') return 'switch';
+    /**
+     * A BOOLEAN input is a switch whether or not anyone declared it.
+     *
+     * Placed after the explicit declarations so a deliberate label still wins, but before the
+     * `value` fallback: the instance will only accept `true`/`false` here, so offering a text
+     * box can only ever produce a rejected prompt. `isBoolean` comes from `object_info`, not
+     * from the stored value's JS type — the stored value is a string for these nodes.
+     */
+    if (isBoolean === true) return 'switch';
+    return 'value';
+}
+
+/**
+ * A switch value, as a real boolean.
+ *
+ * The console sends a `<select>`'s value, which is the string "true" or "false"; a script
+ * may send 1/0 or a bare boolean. All four become `true` / `false` here, once, so nothing
+ * downstream has to guess. Anything unrecognised falls back to false rather than to a
+ * half-truth: "not clearly on" is off.
+ */
+export function normalizeSwitchValue(value) {
+    if (value === true || value === 1) return true;
+    if (value === false || value === 0) return false;
+    const text = String(value ?? '').trim().toLowerCase();
+    if (text === 'true' || text === '1' || text === 'yes' || text === 'on') return true;
+    return false;
+}
+
+/**
+ * Node titles for one graph, keyed by node id.
+ *
+ * Parameter rows are grouped by node in both the editor and the console, and "节点 11" says
+ * far less than "节点 11 · 放大模型 (4x-UltraSharp)". The title lives in the UI graph as
+ * `node._meta.title`, and survivals of it are also read out of an API-format import so one
+ * map serves the whole form.
+ *
+ * Deliberately NOT stored inside `api`: `_meta` on a submitted prompt is tolerated by
+ * ComfyUI, but it is still an extra key travelling to every instance, and the title is a
+ * property of the FORM.
+ */
+export function collectNodeTitles(graph, api = null) {
+    const titles = {};
+    for (const node of Array.isArray(graph?.nodes) ? graph.nodes : []) {
+        if (node === null || typeof node !== 'object') continue;
+        const id = String(node.id ?? '');
+        const title = typeof node?._meta?.title === 'string' ? node._meta.title.trim() : '';
+        if (id !== '' && title !== '') titles[id] = title.slice(0, 80);
+    }
+    for (const [id, node] of Object.entries(api ?? {})) {
+        if (titles[id] !== undefined) continue;
+        const title = typeof node?._meta?.title === 'string' ? node._meta.title.trim() : '';
+        if (title !== '') titles[id] = title.slice(0, 80);
+    }
+    return titles;
+}
+
+/**
+ * Un-associated derived parameters, as [{nodeId, input}].
+ *
+ * Deliberately narrow: no name, no value, no description. This list means exactly one
+ * thing — "do not offer this input in the form" — and anything more would invite storing a
+ * second copy of the value next to the one in the graph. `null` means unchanged, `[]` means
+ * "show everything again", which is how a person undoes a removal wholesale.
+ */
+/**
+ * Operator-declared prompt roles: {positive: [nodeId], negative: [nodeId]}.
+ *
+ * Arrays rather than single ids because a real graph can have two positive encoders (SDXL's
+ * clip_l / clip_g pair, or a base + refiner pair). Duplicates collapse, blanks are dropped,
+ * and a node may not be in both lists — a node that is both positive and negative is a
+ * mistake in the form, not a state the graph can express.
+ */
+export function normalizePromptNodes(value) {
+    if (value === null || value === undefined) return null;
+    if (typeof value !== 'object' || Array.isArray(value)) return null;
+    /**
+     * Entries are node ids or SLOT keys (`15::text_a`).
+     *
+     * A node may hold several string inputs, and each one needs its own role: keying only by
+     * node forced both of 3lora人物's StringFunction inputs to share a single answer, which is
+     * why the editor listed the node twice and neither row could be set independently.
+     */
+    const read = (rows) => {
+        if (!Array.isArray(rows)) return [];
+        const seen = new Set();
+        const out = [];
+        for (const row of rows) {
+            const id = String(row ?? '').trim();
+            if (id === '' || seen.has(id)) continue;
+            seen.add(id);
+            out.push(id);
+        }
+        return out;
+    };
+    const positive = read(value.positive);
+    const negative = read(value.negative).filter((id) => !positive.includes(id));
+    /**
+     * `ignored` names slots the operator parked ON PURPOSE.
+     *
+     * Without it the only way to express "off" was "absent from both lists" — and absence is
+     * indistinguishable from "never classified", so any slot holding text fell back to its
+     * inferred role and came back on after a reload. That made 不参与 one-way: you could switch
+     * a slot on but never off. A slot listed here stays 不参与 no matter what text it holds.
+     *
+     * Kept last in precedence: an explicit positive/negative wins, so a stale `ignored` entry
+     * left behind by an earlier save cannot fight a newer decision.
+     */
+    const ignored = read(value.ignored).filter((id) => !positive.includes(id) && !negative.includes(id));
+    /**
+     * `{positive: [], negative: []}` is a REAL answer, not "unchanged".
+     *
+     * It means "every text node is 不参与" — the operator wants a workflow that takes no
+     * prompt at all, and the console must then show no text box. Collapsing this to `null`
+     * (the old behaviour) made that state inexpressible: the form could never tell
+     * "nothing is assigned" from "nothing was ever said", so every node fell back to its
+     * inferred role and the boxes came back.
+     *
+     * The caller distinguishes the two: `null` = "not provided, keep whatever is stored",
+     * an object (even with empty arrays) = "this is the assignment".
+     */
+    return ignored.length === 0 ? { positive, negative } : { positive, negative, ignored };
+}
+
+/**
+ * Per-node prompt heads, as { "nodeId::input": text }.
+ *
+ * Why per SLOT and not per node: a node can hold several string inputs. `StringFunction|pysssss`
+ * has text_a / text_b / text_c, and a graph like 3lora人物 feeds two of them — so keying by
+ * nodeId alone made the second input OVERWRITE the first. The workbench showed one head box,
+ * the remaining input had no table of its own, and "两个字符串分两个表" was impossible.
+ *
+ * Keys are `nodeId::input`. An old record keyed by bare `nodeId` is still honoured: the
+ * `{input, value}` payload already carried the input name, so it reads back unambiguously and
+ * is rewritten under the slot key on the next save.
+ *
+ * This map only records where a slot's head STARTS, for the slots the operator changed away
+ * from the graph's own text. The authoritative value is still the graph.
+ *
+ * `null`/`undefined` = unchanged; `{}` = clear every override.
+ */
+export function normalizeNodeHeads(value) {
+    if (value === null || value === undefined) return null;
+    if (typeof value !== 'object' || Array.isArray(value)) return null;
+    const out = {};
+    for (const [key, text] of Object.entries(value)) {
+        const rawKey = String(key ?? '').trim();
+        if (rawKey === '') continue;
+        if (text === null || text === undefined) continue;
+        if (typeof text !== 'object') continue;
+        /**
+         * Read the payload first: it names the input, which is what makes a legacy bare
+         * nodeId key recoverable. A key that already carries `::` is trusted as-is.
+         */
+        const payloadInput = String(text.input ?? '').trim();
+        const split = rawKey.indexOf('::');
+        const keyNode = split < 0 ? rawKey : rawKey.slice(0, split);
+        const keyInput = split < 0 ? '' : rawKey.slice(split + 2).trim();
+        const input = keyInput !== '' ? keyInput : payloadInput;
+        if (keyNode === '' || input === '') continue;
+        const body = typeof text.value === 'string' ? text.value : '';
+        out[`${keyNode}::${input}`] = { input, value: body.slice(0, 8000) };
+    }
+    return out;
+}
+
+/** The head text declared for one slot, or undefined when the graph's own text is in force. */
+export function headFor(nodeId, input, nodeHeads) {
+    if (nodeHeads === null || nodeHeads === undefined) return undefined;
+    const slot = `${String(nodeId)}::${String(input)}`;
+    const direct = nodeHeads[slot];
+    if (direct !== undefined && typeof direct === 'object') return direct;
+    /**
+     * A record saved before this change keyed the map by bare nodeId. Only accept it when its
+     * own `input` matches the slot being asked about — otherwise the same entry would be
+     * claimed by every input on that node, which is the bug this function exists to prevent.
+     */
+    const legacy = nodeHeads[String(nodeId)];
+    if (legacy !== undefined && typeof legacy === 'object' && String(legacy.input ?? '') === String(input)) return legacy;
+    return undefined;
+}
+
+/**
+ * Which text node each head belongs to — the legacy, per-role shape.
+ *
+ * Kept because older records and the chain runner still speak it, and because a role with
+ * several candidates still needs "which one is THE positive". New work should use per-node
+ * heads (normalizeNodeHeads): that is what the workbench writes now.
+ */
+export function normalizeHeadNodes(value, promptNodes = null) {
+    const declared = normalizePromptNodes(promptNodes);
+    const allowed = (role) => new Set((declared?.[role] ?? []).map(String));
+    const read = (raw, role) => {
+        const id = String(raw ?? '').trim();
+        if (id === '') return '';
+        const permitted = allowed(role);
+        // An empty declaration means "inferred": anything goes, because the operator has not
+        // said which nodes are which and this is the only place to say where the head is.
+        if (permitted.size === 0) return id;
+        return permitted.has(id) ? id : '';
+    };
+    if (value === null || value === undefined || typeof value !== 'object' || Array.isArray(value)) {
+        return null;
+    }
+    const positive = read(value.positive, 'positive');
+    const negative = read(value.negative, 'negative');
+    if (positive === '' && negative === '') return null;
+    // Only the roles that were actually named. An empty string here would read as "declared
+    // to be node ''", which is not a node — dropping the key is what makes "automatic" the
+    // unambiguous default for the other role.
+    return {
+        ...(positive === '' ? {} : { positive }),
+        ...(negative === '' ? {} : { negative }),
+    };
+}
+
+/**
+ * The console's prompt surface: one box per text node the operator did NOT mark 不参与.
+ *
+ * This is the function the console and the run both read, so the box shown and the node
+ * written cannot drift apart. Three things it settles, in one place:
+ *
+ *   1. **which nodes get a box** — every text row whose role is positive or negative, in
+ *      graph order. A row whose role is `ignored` gets none, and if every row is ignored the
+ *      list is empty: the console then shows no text box at all, which is the requested
+ *      "都选不参与就不显示文本框".
+ *   2. **what each box's standing text is** — per-node heads win (the workbench's inline
+ *      editor), otherwise the node's own encoder text. Never a role-wide "first positive":
+ *      on a two-positive graph that showed one node's text while the run wrote another's.
+ *   3. **where a per-run append lands** — the same node the box came from, with the input
+ *      key carried along.
+ *
+ * Returns `[{nodeId, input, role, classType, head, value}]`, where `head` is the read-only
+ * standing text and `value` the whole encoder string (they differ only when an operator
+ * overrode the head).
+ */
+export function promptBoxes(texts = [], nodeHeads = null, nodeLayers = null, workflowLayers = null) {
+    const rows = Array.isArray(texts) ? texts : [];
+    const heads = normalizeNodeHeads(nodeHeads) ?? {};
+    const boxes = [];
+    for (const row of rows) {
+        const role = row?.role === 'negative' ? 'negative' : (row?.role === 'ignored' ? 'ignored' : 'positive');
+        if (role === 'ignored') continue;
+        const nodeId = String(row.nodeId);
+        const input = String(row.input);
+        const graphText = typeof row.value === 'string' ? row.value : '';
+        // A head belongs to a SLOT, not a node: a node with two strings gets two heads.
+        const override = headFor(nodeId, input, heads);
+        const head = override !== undefined ? override.value : graphText;
+        boxes.push({
+            nodeId,
+            input,
+            role,
+            classType: String(row.classType ?? ''),
+            head,
+            value: head,
+            /**
+             * This node's own layers, even when empty.
+             *
+             * Every box carries the list — not just the positive one — because the console
+             * renders one layer box per entry underneath THAT box. A negative encoder with
+             * its own 排除项 / 画质 split is the case this exists for.
+             */
+            layers: layersForNode(nodeId, nodeLayers, workflowLayers),
+        });
+    }
+    return boxes;
+}
+
+/**
+ * Does this workflow take any prompt text at all?
+ *
+ * `false` when the graph has no text node, and also when the operator marked every one of
+ * them 不参与 — the console hides its whole prompt section in both cases, because a box that
+ * nobody reads is worse than no box.
+ */
+export function hasPromptBoxes(texts = []) {
+    return promptBoxes(texts, null).length > 0;
+}
+
+/**
+ * Flatten a head-node declaration into the lookup `promptTargets` accepts.
+ *
+ * `promptTargets` already takes `{positive: [ids], negative: [ids]}`. A head declaration
+ * answers the same question with one id per role, and it must WIN over the broader roles —
+ * that is the whole point: on a two-positive graph the roles say "both are positive", and
+ * only the head declaration says which one the console types into.
+ *
+ * NOTE: the workbench no longer writes `headNodes` (heads are per node now). This stays for
+ * old records and for the chain runner, which still speaks roles.
+ */
+export function headRoles(promptNodes = null, headNodes = null) {
+    const declared = normalizePromptNodes(promptNodes);
+    const heads = normalizeHeadNodes(headNodes, declared);
+    if (heads === null) return declared;
+    /**
+     * A role the declaration does not name keeps its full declared list.
+     *
+     * `null` must not sneak in here: the shape `promptTargets` accepts is arrays of ids, and
+     * a `[null]` would be compared against a node id, never match, and silently relabel the
+     * negative encoder as positive.
+     */
+    const narrowed = (role) => {
+        const chosen = String(heads?.[role] ?? '') !== '';
+        return chosen ? [String(heads[role])] : (declared?.[role] ?? []);
+    };
+    return { positive: narrowed('positive'), negative: narrowed('negative') };
+}
+
+/**
+ * The node ONE head box addresses, per role — legacy companion to `headRoles`.
+ *
+ * New code should use `promptBoxes`, which is per node. This one still answers "which single
+ * node is THE positive", which is what a per-run `heads` override needs.
+ */
+export function headTargets(texts = [], headNodes = null) {
+    const rows = Array.isArray(texts) ? texts : [];
+    const declared = headNodes !== null && typeof headNodes === 'object' ? headNodes : {};
+    const pick = (role) => {
+        const wanted = String(declared?.[role] ?? '');
+        const ofRole = rows.filter((row) => (role === 'negative' ? row.role === 'negative' : row.role === 'positive'));
+        const exact = wanted === '' ? undefined : ofRole.find((row) => String(row.nodeId) === wanted);
+        const chosen = exact ?? ofRole[0];
+        if (chosen === undefined) return null;
+        return { nodeId: String(chosen.nodeId), input: String(chosen.input) };
+    };
+    return { positive: pick('positive'), negative: pick('negative') };
+}
+
+export function normalizeParamHidden(value) {
+    if (value === null || value === undefined) return null;
+    if (!Array.isArray(value)) return null;
+    const seen = new Set();
+    const rows = [];
+    for (const entry of value) {
+        if (entry === null || typeof entry !== 'object') continue;
+        const nodeId = String(entry.nodeId ?? '').trim();
+        const input = String(entry.input ?? '').trim();
+        if (nodeId === '' || input === '') continue;
+        const key = `${nodeId}::${input}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        rows.push({ nodeId, input });
+        if (rows.length >= MAX_PARAM_PICKS) break;
+    }
+    return rows;
+}
+
+export function normalizeParamPicks(value) {
+    if (value === null || value === undefined) return null;
+    if (!Array.isArray(value)) return null;
+    const seen = new Set();
+    const rows = [];
+    for (const entry of value) {
+        if (entry === null || typeof entry !== 'object') continue;
+        const nodeId = String(entry.nodeId ?? '').trim();
+        // `input` is the graph key; it is kept because that is what generate() writes into.
+        const input = String(entry.input ?? '').trim();
+        if (nodeId === '' || input === '') continue;
+        const key = `${nodeId}::${input}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        const rawValue = entry.value;
+        const kind = normalizeParamKind(entry, input);
+        rows.push({
+            name: String(entry.name ?? '').trim().slice(0, 60) || input,
+            nodeId,
+            input,
+            // Keep the type: a number stays a number, or the graph receives "20" where it
+            // expects 20 and ComfyUI rejects the prompt. A switch is the same argument one
+            // step further: `true` has to stay a boolean, and "true" has to be coerced here
+            // rather than at submit time, or the form shows "false" for a truthy string.
+            value: kind === 'switch'
+                ? normalizeSwitchValue(rawValue)
+                : (typeof rawValue === 'number' || typeof rawValue === 'string' ? rawValue : ''),
+            desc: String(entry.desc ?? '').trim().slice(0, 200),
+            /**
+             * What kind of value this parameter takes: value / model / seed / switch.
+             *
+             * "model" makes the console render a dropdown of files from `folder` instead of
+             * a free-text box, so the operator picks a LoRA from the LoRA folder rather than
+             * typing a filename that must match byte for byte.
+             *
+             * "seed" is a sampling seed, and one of the two kinds with a mode: random (draw a
+             * fresh 12-digit number per run) or fixed (use `seedMode`'s number every time).
+             * The mode is stored here rather than in the graph because it is a property of
+             * the form — writing it into `inputs` would submit a key ComfyUI rejects.
+             *
+             * "switch" is a boolean input, offered as true/false and nothing else. Its value
+             * is always a real boolean (see normalizeSwitchValue): a BOOLEAN input rejects
+             * "true" and 1, and that rejection only shows up after the job is queued.
+             *
+             * Model parameters are NSFW-only. Not a content judgement — picking model files
+             * is an operator capability, and the SFW surface stays a plain parameter form.
+             * The gate is enforced on the server (see visibleParams), so a SFW account
+             * cannot obtain one by hand-editing a request.
+             */
+            kind,
+            /** Model folder to list; only meaningful when kind is "model". */
+            folder: String(entry.folder ?? '').trim().slice(0, 40),
+            /** Seed mode; only meaningful when kind is "seed". */
+            ...(kind === 'seed'
+                ? { seedMode: String(entry.seedMode ?? '') === 'fixed' ? 'fixed' : 'random' }
+                : {}),
+        });
+        if (rows.length >= MAX_PARAM_PICKS) break;
+    }
+    return rows;
+}
+
+/**
+ * Parse a free-text parameter list into the four-field shape.
+ *
+ * The point is speed: an operator pastes a block copied from a note or a chat and gets rows,
+ * rather than clicking "add" forty times. Accepted per line, in any of these shapes:
+ *
+ *   步数 | 3 | steps | 采样步数
+ *   步数, 3, steps, 采样步数
+ *   步数 = 3      (nodeId then assumed to be the first node that has such an input)
+ *   步数 3
+ *
+ * Fields are `name, value, nodeId, desc` — the order a person writes when describing a
+ * parameter: what it is called, what it is set to, where it lives, why.
+ *
+ * Lines that cannot be understood are returned in `problems` rather than dropped silently:
+ * a paste that half-parses is worse than one that says which line it did not like.
+ */
+export function parseParamText(text, api = null) {
+    const rows = [];
+    const problems = [];
+    const lines = String(text ?? '').split(/\r?\n/);
+    for (let index = 0; index < lines.length; index += 1) {
+        const raw = lines[index].trim();
+        if (raw === '' || raw.startsWith('#')) continue;
+        // '|' and ',' and tab are all things people paste; '=' only separates name from value.
+        const parts = raw.split(/\s*[|,，\t]\s*/).map((part) => part.trim());
+        const equal = /^([^=]+)=(.+)$/.exec(raw);
+        let name;
+        let value;
+        let nodeId;
+        let desc;
+        if (parts.length >= 2) {
+            [name, value, nodeId = '', desc = ''] = parts;
+        } else if (equal !== null) {
+            name = equal[1].trim();
+            value = equal[2].trim();
+            nodeId = '';
+            desc = '';
+        } else {
+            const spaced = /^(\S+)\s+(.+)$/.exec(raw);
+            if (spaced === null) {
+                problems.push(`第 ${index + 1} 行看不懂：${raw.slice(0, 40)}`);
+                continue;
+            }
+            name = spaced[1];
+            value = spaced[2].trim();
+            nodeId = '';
+            desc = '';
+        }
+        if (name === '' || value === '') {
+            problems.push(`第 ${index + 1} 行缺少名称或默认值：${raw.slice(0, 40)}`);
+            continue;
+        }
+        /**
+         * The name must match an input key in the graph EXACTLY.
+         *
+         * Fuzzy matching was tried and rejected: "步数" quietly bound to `steps`, and when
+         * two nodes both had a `steps` the paste silently picked one. A parameter that binds
+         * to the wrong node fails at run time with an error that names neither, so this
+         * refuses instead — an unrecognised name is reported with the node ids that DO have
+         * a key of that name, which is the information needed to fix it.
+         *
+         * `nodeId` may be given to disambiguate; without it, the name must be unique.
+         */
+        const matches = Object.entries(api ?? {}).filter(([, node]) =>
+            Object.prototype.hasOwnProperty.call(node?.inputs ?? {}, name),
+        );
+        let chosen = nodeId;
+        if (chosen !== '') {
+            const node = api?.[chosen];
+            if (node === undefined) {
+                problems.push(`第 ${index + 1} 行的节点 ${chosen} 在 JSON 里不存在：${name}`);
+                continue;
+            }
+            if (!Object.prototype.hasOwnProperty.call(node.inputs ?? {}, name)) {
+                problems.push(`第 ${index + 1} 行：节点 ${chosen} 没有输入 ${name}`);
+                continue;
+            }
+        } else if (matches.length === 1) {
+            chosen = String(matches[0][0]);
+        } else if (matches.length === 0) {
+            problems.push(`第 ${index + 1} 行：JSON 里找不到名为 ${name} 的输入`);
+            continue;
+        } else {
+            const ids = matches.map(([id, node]) => `${id}(${String(node?.class_type ?? '')})`).join('、');
+            problems.push(`第 ${index + 1} 行：${name} 出现在多个节点上（${ids}），请补上节点 id`);
+            continue;
+        }
+        const numeric = /^-?\d+(\.\d+)?$/.test(value);
+        rows.push({
+            // The name IS the graph key; they are not two things that could disagree.
+            name: name.slice(0, 60),
+            nodeId: chosen,
+            input: name.slice(0, 60),
+            value: numeric ? Number(value) : value,
+            desc: desc.slice(0, 200),
+        });
+        if (rows.length >= MAX_PARAM_PICKS) break;
+    }
+    return { params: rows, problems };
+}
+
+/**
+ * Accept a heads object from a caller and keep exactly two trimmed strings.
+ *
+ * `null` means "the caller said nothing", which is different from "the caller
+ * cleared the heads": an empty string is a real value, and it is how a workflow
+ * declares that it must have no prefix at all.
+ */
+export function normalizeHeads(value) {
+    if (value === null || value === undefined || typeof value !== 'object') return null;
+    const positive = typeof value.positive === 'string' ? value.positive.trim() : '';
+    const negative = typeof value.negative === 'string' ? value.negative.trim() : '';
+    return { positive, negative };
+}
+
+/**
+ * Ordered positive-prompt layers, e.g. [{name:'面部'},{name:'躯干'},{name:'环境'}].
+ *
+ * Why a workflow-level list and not three fixed fields: which parts a person wants to
+ * describe separately depends on the graph. A portrait wants face/hair/clothes, a scene
+ * wants foreground/subject/background, an upscaler wants none. So the *workflow* declares
+ * the layer names and their order, and the console renders one box per layer.
+ *
+ * Order is the array order and nothing else — that is the whole contract, because the
+ * assembled prompt is what the model sees. Names are labels only; an empty name is
+ * allowed and the console shows it as "第 N 层".
+ *
+ * `null` means "unchanged / not provided"; `[]` means "this workflow has no layers",
+ * which is a real value and must clear a previous definition.
+ */
+export function normalizeLayers(value) {
+    if (value === null || value === undefined) return null;
+    if (!Array.isArray(value)) return null;
+    return value
+        .filter((row) => row !== null && typeof row === 'object')
+        .map((row) => ({ name: typeof row.name === 'string' ? row.name.trim().slice(0, 40) : '' }))
+        .slice(0, MAX_LAYERS);
+}
+
+/** Cap: more than this is not a layered prompt, it is a spreadsheet. */
+export const MAX_LAYERS = 8;
+
+/**
+ * Per-node prompt layers, as `{ nodeId: [{name}, …] }`.
+ *
+ * Why per NODE and not per workflow: a graph with several text nodes needs its own layering
+ * for each of them. A negative encoder wants 排除项 / 画质 / 水印; a negative prompt is not
+ * "the same layers as the positive". The old workflow-level list forced every node to share
+ * one shape, so the console could only ever layer the positive and the negative had to be one
+ * blob.
+ *
+ * Shape mirrors `nodeHeads`: a map keyed by nodeId, `null` = unchanged, `{}` = clear every
+ * per-node definition. A node with no entry simply has no layers (one box), which is the
+ * right default for a graph that never needed them.
+ *
+ * Order inside a node's array is the assemble order and nothing else; names are labels, and
+ * an empty name is shown as "第 N 层".
+ */
+export function normalizeNodeLayers(value) {
+    if (value === null || value === undefined) return null;
+    if (typeof value !== 'object' || Array.isArray(value)) return null;
+    const out = {};
+    for (const [key, rows] of Object.entries(value)) {
+        const nodeId = String(key ?? '').trim();
+        if (nodeId === '') continue;
+        /**
+         * An EMPTY list is kept, and it is load-bearing.
+         *
+         * `[]` means "this node is not layered"; no entry means "fall back to the
+         * workflow-level list". Dropping empty arrays collapsed the first into the second, so
+         * deleting a node's last layer silently restored the old shared split on the next
+         * render — the operator removed 面部/躯干 and 面部/躯干 came back.
+         */
+        if (rows === null || (Array.isArray(rows) && rows.length === 0)) {
+            out[nodeId] = [];
+            continue;
+        }
+        if (!Array.isArray(rows)) continue;
+        const list = rows
+            .filter((row) => row !== null && typeof row === 'object')
+            .map((row) => ({ name: typeof row.name === 'string' ? row.name.trim().slice(0, 40) : '' }))
+            .slice(0, MAX_LAYERS);
+        out[nodeId] = list;
+    }
+    return out;
+}
+
+/**
+ * The layer definitions one text node should use.
+ *
+ * Per-node wins; the workflow-level `layers` is the fallback so workflows written before this
+ * change keep their single set of layer names on their positive encoder instead of silently
+ * losing them.
+ */
+export function layersForNode(nodeId, nodeLayers = null, workflowLayers = null) {
+    const map = normalizeNodeLayers(nodeLayers) ?? {};
+    const id = String(nodeId ?? '');
+    if (map[id] !== undefined) return map[id];
+    const fallback = Array.isArray(workflowLayers) ? workflowLayers : [];
+    return fallback
+        .filter((row) => row !== null && typeof row === 'object')
+        .map((row) => ({ name: typeof row.name === 'string' ? row.name.trim() : '' }))
+        .slice(0, MAX_LAYERS);
+}
+
+/**
+ * Assemble layered text into one positive prompt, in declared order.
+ *
+ * Empty layers are skipped rather than joining to an empty slot, so a person can leave
+ * 躯干 blank without producing "面部, , 环境". Joined with ", " — the same separator the
+ * rest of the prompt pipeline uses, so the result is indistinguishable from someone having
+ * typed the whole thing by hand.
+ */
+export function joinLayers(values) {
+    return values
+        .map((value) => String(value ?? '').trim().replace(/^[,，]\s*|\s*[,，]$/g, ''))
+        .filter((value) => value !== '')
+        .join(', ');
+}