@melite/models-mask 0.0.0-stage → 0.1.5-pre-alpha

package/lib/actions.js

@@ -0,0 +1,502 @@
+import { impactDetector } from '@melite/comfyui-card-kit/impact';
+const isSpell = (s) => s.startsWith('$');
+const personDetector = impactDetector('person');
+const faceDetector = impactDetector('face');
+const handDetector = impactDetector('hand');
+/** The family's three weight names — the lane's own constants (the
+ *  LANE_FILES pattern, the h3 precedent: clip/vae_video/vae_audio
+ *  never ride a row either). No variant of this family swaps a
+ *  weight and no user picks one, so they live beside the build that
+ *  wires them; the card's provisions declare the downloads, and
+ *  image/mask/tests/card.spec.ts pins the agreement (a weight the
+ *  lane loads that no provision downloads is a silent
+ *  wrong-weights run — the same law the variant cells carry). */
+export const MASK_WEIGHTS = {
+    checkpoint: 'sam3.1_multiplex_fp16.safetensors',
+    unet: 'rt_detr_v4-x-hgnet_fp32.safetensors',
+    sam2: 'sam2.1_hiera_large.pt',
+};
+/** The family's facts door: the lane reads NOTHING off a row (the
+ *  three weights are the family's constants above), so the door
+ *  returns them closed — an empty loader name is unrepresentable,
+ *  which is the old refusal law (a pin that is not a non-empty
+ *  string refused here) held by construction. The registry still
+ *  exercises this door at registration over the empty family row.
+ *  @param _raw the resolved lane_inputs (empty on this family)
+ *  @returns the three weights the lane wires into its loaders */
+export function parseMaskLaneFacts(_raw) {
+    return { checkpoint: MASK_WEIGHTS.checkpoint, unet: MASK_WEIGHTS.unet, sam2: MASK_WEIGHTS.sam2 };
+}
+/** THE TUNE VOCABULARY IS DERIVED FROM ITS OWN TYPE (the census's
+ *  L1): the runtime list and the compile-time type were written side
+ *  by side, so adding a key to one and not the other was silent — the
+ *  gate accepted a key the type did not carry (or refused one it
+ *  did). The keys are the type's own members now; the assertion
+ *  below fails if the two ever part company. */
+export const TUNE_KEYS = [
+    'threshold', 'refine', 'dilation', 'detection_threshold', 'box_expansion',
+    'hint_threshold', 'detection_dilation', 'crop_factor', 'drop_size',
+];
+/** THE MASK SELECTION ACTION (the family's one declared lane): the
+ *  input_image admission stays on the card; this is the lane alone.
+ *  TWO selection families: the SAM3 CLIP/RT-DETR leg (checkpoint +
+ *  unet weights) and the SAM2 impact-pack arm (sam2 + the pack's own
+ *  specialized detectors — person on segm, face/hand on their bbox
+ *  models — the detector proposes, SAM2 refines). */
+export const select = {
+    id: "select",
+    inputs: [],
+    outputs: [{ name: "default", kind: "MASK" }],
+    params: [],
+    facts: parseMaskLaneFacts,
+    build({ p, facts, g, runId }) {
+        const li = { checkpoint: facts.checkpoint, unet: facts.unet, sam2: facts.sam2 }; // the family's weight constants (MASK_WEIGHTS above)
+        const prefix = `${runId}/mask`; // the arm's "%s/mask" % run_id
+        const samThreshold = p.sam_threshold;
+        // undeclared legacy renderer keys ride the door's explicit-params
+        // overlay (see schema header) — schema-required paint_mask renders
+        // ''-absent at compose (image-gen precedent), refine_iterations
+        // falls back to its old schema pin 2 when no explicit names it.
+        const refineIterations = (p.refine_iterations ?? 2);
+        const dilation = p.sam_dilation;
+        
+        // ImpactSimpleDetectorSEGS: sub_bbox_expansion +
+        // sam_mask_hint_threshold were hard-pinned and unexposed): the
+        // lane-flat seat is the PRIMARY sam2's fold; absent (a sam3
+        // primary, pre-fold benches) = the pack's own defaults.
+        const bboxExpansion = p.box_expansion ?? 0;
+        const hintThreshold = p.hint_threshold ?? 0.7;
+        
+        // three hard-pinned knobs): node-faithful defaults (10 / 3 / 10 —
+        // what the lane always shipped), now per-entry overridable.
+        const detectionDilation = p.detection_dilation ?? 10;
+        const cropFactor = p.crop_factor ?? 3.0;
+        const dropSize = p.drop_size ?? 10;
+        const exportBoxes = p.export_boxes;
+        const viaRtdetr = p.primary_via_rtdetr;
+        // the lazy loader trio (see the header note — created on first use)
+        // THE SPELLED ANCHOR (the mask-as-consumer half of the gap
+        // audit: a producer-wired input_image rides every tensor slot
+        // verbatim, never a LoadImage — ROW-4 refuses producer links in
+        // file slots, so the loader builds for paths only).
+        let imgH = null;
+        let ckpt = null;
+        let rtdetrModel = null;
+        const img = () => (imgH ??= isSpell(p.input_image)
+            ? p.input_image
+            : g.node('LoadImage', { image: p.input_image }).out(0));
+        const ckptNode = () => (ckpt ??= g.node('CheckpointLoaderSimple', { ckpt_name: li.checkpoint }));
+        const rtdetrLoader = () => (rtdetrModel ??= g.node('UNETLoader', { unet_name: li.unet, weight_dtype: 'default' }).out(0));
+        const clipCond = (text) => g.node('CLIPTextEncode', { text, clip: ckptNode().out(1) }).out(0);
+        const detect = (conditioning, bboxes, tune) => {
+            const inputs = {
+                model: ckptNode().out(0),
+                image: img(),
+                threshold: tune?.threshold ?? samThreshold,
+                refine_iterations: tune?.refine ?? refineIterations,
+                individual_masks: false,
+            };
+            if (conditioning)
+                inputs.conditioning = conditioning;
+            
+            // the old DEFAULT_BBOXES autofilled {0,0,512,512} on every
+            // unscoped detection — a top-left QUARTER "hint" on any image
+            // larger than 512, silently blinding the selection everywhere
+            // else (an empty mask on a 1024px input, proven live).
+            // Unscoped = bboxes rides ABSENT = search the WHOLE image; the
+            // drawn Region scope (and RT-DETR's own boxes) still thread as
+            // the explicit hint when they exist.
+            if (bboxes !== undefined)
+                inputs.bboxes = bboxes;
+            return g.node('SAM3_Detect', inputs).out(0); // (masks, bboxes) → masks
+        };
+        const dilate = (mask, d) => (d ?? dilation) ? g.node('GrowMask', { mask, expand: d ?? dilation, tapered_corners: true }).out(0) : mask;
+        // the lane's declared output is the mask it saved last (the card's
+        // output binding reads that SaveImage); the handle rides the same
+        // node, so nothing is created, moved or renumbered by declaring it
+        let saved = null;
+        const save = (mask, name, d) => {
+            const m2i = g.node('MaskToImage', { mask: dilate(mask, d) });
+            saved = g.node('SaveImage', { images: m2i.out(0), filename_prefix: `${prefix}/${name}` }).out(0);
+        };
+        // THE RECT SCOPE (the drawn box — the bbox-canvas leaf's
+        // [x, y, w, h] pixels): a zeros W×H mask plus a ones w×h box at
+        // (x, y) (MaskComposite add), multiplied over the selection. CORE
+        // nodes only (SolidMask + MaskComposite + GetImageSizeAndCount —
+        // all live on every engine; the scope never depends on the
+        // impact arm that made the mask).
+        const rectMask = (scope) => {
+            const size = g.node('GetImageSizeAndCount', { image: img() });
+            const zeros = g.node('SolidMask', { value: 0, width: size.out(1), height: size.out(2) }).out(0);
+            const ones = g.node('SolidMask', { value: 1, width: scope.width, height: scope.height }).out(0);
+            return g.node('MaskComposite', { destination: zeros, source: ones, x: scope.x, y: scope.y, operation: 'add' }).out(0);
+        };
+        const scopeMask = (mask, scope) => g.node('MaskComposite', { destination: mask, source: rectMask(scope), x: 0, y: 0, operation: 'multiply' }).out(0);
+        // THE SAM2 IMPACT-PACK ARM (the operator's SAM2: the detector
+        // proposes + SAM2 refines; the mask card declares the packs +
+        // weights, the compose door refuses without them — never a
+        // silent CLIP leg). UltralyticsDetectorProvider (subpack, the
+        // card's PINNED detector model: segm/person for person,
+        // bbox/face + bbox/hand for face/hand) → SegmDetectorSEGS or
+        // BboxDetectorSEGS (image + the detector boxes + the card's
+        // labels) → SEGS → SAMDetectorCombined (PINNED sam2 model,
+        // center-1 — the pack's own best-practice default) → MASK. The
+        // drawn box scopes after (the rect scope above).
+        let samH = null;
+        let segmH = null;
+        let faceH = null;
+        let handH = null;
+        const samLoader = () => (samH ??= g.node('SAMLoader', { model_name: li.sam2, device_mode: 'AUTO' }).out(0));
+        
+        // pack's own detailer-pipe-test wires SegmDetectorSEGS — a
+        // segmentation detector whose boxes come from CLASS-PIXEL masks
+        // (tighter crops, no center-point guess). The detector model
+        // comes from the card kit's detector catalog
+        
+        // downloaded + provision-declared that night).
+        const segmProvider = () => 
+        
+        // wiring it into SegmDetectorSEGS.segm_detector 400s the run
+        // with return_type_mismatch; the provider's own output list
+        // is ["BBOX_DETECTOR", "SEGM_DETECTOR"]).
+        (segmH ??= g.node(personDetector.providerNode, { model_name: personDetector.graphPath }).out(personDetector.providerOutput));
+        const faceProvider = () => (faceH ??= g.node(faceDetector.providerNode, { model_name: faceDetector.graphPath }).out(faceDetector.providerOutput));
+        const handProvider = () => (handH ??= g.node(handDetector.providerNode, { model_name: handDetector.graphPath }).out(handDetector.providerOutput));
+        
+        // "ONLY the ones shown in the Impact Pack examples" — person,
+        // face, hand, each on the pack's OWN specialized detector, exactly
+        // as detailer-pipe-test.json wires them). A mixed set (person +
+        // face) cannot share one detector call — split it across two sam2
+        // entries, each with its own export. Refuses LOUD, never a
+        // half-detected entry.
+        const sam2detect = (labels, scope, tune) => {
+            if (labels === '') {
+                throw new Error('maskT1: a sam2 selection needs labels (a detector class word — the card refuses empty)');
+            }
+            const words = labels.split(',').map((w) => w.trim()).filter((w) => w !== '');
+            const fams = new Set(words.map((w) => w === 'person' ? 'segm' : 'bbox'));
+            if (fams.size > 1) {
+                throw new Error(`maskT1: one detector per sam2 entry — '${labels}' mixes detector families (person rides segm, face/hand ride bbox). Split it across two sam2 entries.`);
+            }
+            const segmLane = words[0] === 'person';
+            // (ImpactSimpleDetectorSEGS was AUDITED and REJECTED for this
+            // lane: it carries NO labels input — the class filter, the
+            // operator's core demand, cannot ride it. The pack's own
+            // labels-filtering test workflow (detailer-pipe-test.json)
+            // wires BboxDetectorSEGS + SAMDetectorCombined exactly as
+            // this lane does.)
+            // THE WORD→FACTS MAP (the stroke's pin law, verbatim shape):
+            // person rides the segm facts, face its bbox facts, EVERYTHING
+            // else (hand, the 'all' wildcard, unstated words) the hand bbox
+            // facts with labels verbatim — the pre-stroke ternary's exact
+            // graph, only the pin source moved (caller strings → pack facts).
+            const detector = segmLane ? personDetector
+                : words[0] === 'face' ? faceDetector : handDetector;
+            const provider = segmLane ? segmProvider()
+                : words[0] === 'face' ? faceProvider() : handProvider();
+            const segs = g.node(detector.detectorNode, {
+                [detector.detectorInput]: provider,
+                image: img(),
+                threshold: (tune?.detection_threshold ?? p.detection_threshold ?? 0.5),
+                dilation: tune?.detection_dilation ?? detectionDilation,
+                crop_factor: tune?.crop_factor ?? cropFactor,
+                drop_size: tune?.drop_size ?? dropSize,
+                labels,
+            }).out(0);
+            // THE PER-INSTANCE CROPS (the gap audit's #3/#4 export half):
+            // SEGSToImageList unwraps one crop per detected instance —
+            // PreviewImage saves each — the per-instance readback the
+            // pack's own examples ride (SEGSToImageList in
+            // detailer-pipe-test + 5-prompt-per-tile). Automatic: the
+            // crops ARE the manifest's granular sibling.
+            g.node('SaveImage', {
+                images: g.node('SEGSToImageList', { segs }).out(0),
+                filename_prefix: `${runId}/instance`,
+            });
+            const refined = g.node('SAMDetectorCombined', {
+                sam_model: samLoader(),
+                segs,
+                image: img(),
+                detection_hint: 'center-1',
+                dilation: tune?.dilation ?? dilation,
+                threshold: tune?.threshold ?? samThreshold,
+                bbox_expansion: tune?.box_expansion ?? bboxExpansion,
+                mask_hint_threshold: tune?.hint_threshold ?? hintThreshold,
+                mask_hint_use_negative: 'False',
+            }).out(0);
+            const mask = scope ? scopeMask(refined, scope) : refined;
+            return { mask, segs };
+        };
+        let primaryMask = null;
+        let primarySegs = null;
+        // THE PRIMARY SCOPE (the first standalone entry's drawn box —
+        // the card threads it as scope_bbox; absent = unscoped). Every
+        // SELECTION primary honors it; the paint primary never does (the
+        // strokes ARE the mask — a scope would cut them).
+        const scopeQuad = p.scope_bbox;
+        const primaryScope = scopeQuad && scopeQuad.length === 4
+            ? { x: scopeQuad[0], y: scopeQuad[1], width: scopeQuad[2], height: scopeQuad[3] }
+            : undefined;
+        // ── the RT-DETR proposal lane (primary body + box manifest) ──
+        let rtdetrBoxes = null;
+        if (exportBoxes || viaRtdetr) {
+            
+            // NO CAP ("0 = no cap" on the card's schema) and `|| 100` both
+            // capped it and coerced every falsy value — so a default-omitted
+            // request silently dropped detections past 100.
+            const stated = p.max_instances;
+            const cap = stated === undefined || stated === 0 ? 0 : stated;
+            rtdetrBoxes = g.node('RTDETR_detect', {
+                model: rtdetrLoader(),
+                image: img(),
+                threshold: p.detection_threshold,
+                class_name: 'person',
+                max_detections: cap,
+            }).out(0);
+        }
+        const primaryClass = p.primary_class;
+        const primaryPrompt = p.primary_prompt;
+        const viaSam2 = p.primary_via_sam2;
+        const primarySam2Labels = p.primary_sam2_labels;
+        if (viaRtdetr && rtdetrBoxes) {
+            primaryMask = detect(undefined, rtdetrBoxes);
+            if (primaryScope)
+                primaryMask = scopeMask(primaryMask, primaryScope);
+            save(primaryMask, 'mask_combined');
+        }
+        else if (viaSam2) {
+            const det = sam2detect(primarySam2Labels ?? 'all', primaryScope);
+            primaryMask = det.mask;
+            primarySegs = det.segs;
+            save(primaryMask, 'mask_combined');
+            
+            // going to select figure one or figure two"): the pack's own
+            // ImpactSEGSPicker takes the primary detection's SEGS + a
+            // 1-based pick ("2" = the second detected instance) and each
+            // figure saves its own refined mask (mask_figure_<n>) — the
+            // agent selects a figure by composing with figures: [2], no
+            // manual box anywhere. The per-instance image crops
+            // (run/instance) are the visual index into the same numbering.
+            const figs = p.sam2_figures;
+            if (figs !== undefined) {
+                if (!Array.isArray(figs) || figs.some((n) => !Number.isInteger(n) || n < 1)) {
+                    throw new Error(`maskT1: sam2_figures must be 1-based instance numbers — got ${JSON.stringify(figs).slice(0, 60)}`);
+                }
+                for (const n of [...new Set(figs)]) {
+                    const picked = g.node('ImpactSEGSPicker', { picks: String(n), segs: primarySegs }).out(0);
+                    // THE FIGURES RIDE THE SAME TWO-STEP (the operator's
+                    
+                    // YOLO/Segm, THEN extract the mask off the filtered area"):
+                    // the picker NARROWS the SEGS to figure <n>, then
+                    // SAMDetectorCombined refines THAT subset exactly as the
+                    // combined arm does — per-figure SAM masks for EVERY class
+                    // (person's YOLO segm OR face/hand's bare bbox crops alike;
+                    // SegsToCombinedMask alone would have rendered step-one
+                    // masks — rectangles on the bbox classes). Same loader
+                    // node, same pack-test scalars, the primary's own
+                    // dilation/threshold.
+                    const figMask = g.node('SAMDetectorCombined', {
+                        sam_model: samLoader(),
+                        segs: picked,
+                        image: img(),
+                        detection_hint: 'center-1',
+                        dilation,
+                        threshold: samThreshold,
+                        bbox_expansion: bboxExpansion,
+                        mask_hint_threshold: hintThreshold,
+                        mask_hint_use_negative: 'False',
+                    }).out(0);
+                    save(primaryScope ? scopeMask(figMask, primaryScope) : figMask, `mask_figure_${n}`);
+                }
+            }
+        }
+        else if (primaryClass) {
+            // the drawn Region threads as the detect HINT too (the wall
+            // caught it: exports threaded theirs, the primary did not —
+            // the hint narrows the search, the multiply guarantees bounds)
+            primaryMask = detect(clipCond(primaryClass), primaryScope);
+            if (primaryScope)
+                primaryMask = scopeMask(primaryMask, primaryScope);
+            save(primaryMask, 'mask_combined');
+        }
+        else if (primaryPrompt) {
+            primaryMask = detect(clipCond(primaryPrompt), primaryScope);
+            if (primaryScope)
+                primaryMask = scopeMask(primaryMask, primaryScope);
+            save(primaryMask, 'mask_combined');
+        }
+        else if (p.primary_is_paint) {
+            // NOTE: the engine primary `painted` and the exports' `paint_masked`
+            // are DISTINCT locals — a paint primary plus a paint export renders
+            // TWO LoadImageMask nodes (byte-identical inputs, two nodes). The
+            // probe pins this.
+            const painted = g.node('LoadImageMask', { image: (p.paint_mask ?? ''), channel: 'alpha' }).out(0);
+            primaryMask = painted;
+            save(painted, 'mask_combined');
+        }
+        // ── per-name exports ──
+        // the third arm (optional) = the per-entry bbox [x, y, w, h];
+        // the fourth arm (optional) = the per-entry TUNE (stroke 95 —
+        // every knob a mask source owns rides its bag entry): threshold
+        // / refine / dilation / detection_threshold overrides for THIS
+        // export's selection. Malformed refuses LOUD (a drifted bag is
+        // drift, never a skip); absent arms ride the lane-flat values
+        // (the primary's tune — the card threads it flat).
+        const exports = p.exports ?? [];
+        const kinds = p.export_kind ?? [];
+        const entryTune = (raw) => {
+            if (raw === undefined || raw === null)
+                return undefined;
+            if (typeof raw !== 'object' || Array.isArray(raw)) {
+                throw new Error(`maskT1: an export tune must be an object (threshold/refine/dilation/detection_threshold) — got ${JSON.stringify(raw).slice(0, 60)}`);
+            }
+            const t = raw;
+            
+            // once covered only 4 of 9 keys — the 5 newer knobs flowed
+            // unvalidated to node inputs, an engine 400 instead of a loud
+            // lane refusal). Every value in a tune is a finite number.
+            // the key set is the type's own members (TUNE_KEYS is derived),
+            // so the membership test narrows the runtime string
+            const known = new Set(TUNE_KEYS);
+            const unknown = Object.keys(t).filter((k) => !known.has(k));
+            if (unknown.length > 0) {
+                throw new Error(`maskT1: an export tune carries unknown key(s) ${unknown.join(', ')} — the vocabulary is ${TUNE_KEYS.join('/')}`);
+            }
+            for (const key of Object.keys(t)) {
+                const v = t[key];
+                if (typeof v !== 'number' || !Number.isFinite(v)) {
+                    throw new Error(`maskT1: an export tune's '${key}' must be a finite number — got ${JSON.stringify(v).slice(0, 40)}`);
+                }
+            }
+            return t;
+        };
+        // SCOPE VALIDATION (the lane's own gate — the card threads the
+        // primary entry's box here; a malformed quad refuses LOUD, never
+        // a silently unscoped primary).
+        if (scopeQuad && scopeQuad.length !== 4) {
+            throw new Error(`scope_bbox refused on the mask-studio card: needs exactly [x, y, w, h] pixels (got ${scopeQuad.length} values)`);
+        }
+        // PER-ENTRY PAINT PAYLOADS (the ordered-draw law, stroke 78): each
+        // draw owns its PNG — cached by path (two draws on one payload
+        // render ONE LoadImageMask; two payloads render two).
+        const paintByPath = new Map();
+        const loadPaint = (path) => {
+            let m = paintByPath.get(path);
+            if (m === undefined) {
+                m = g.node('LoadImageMask', { image: path, channel: 'alpha' }).out(0);
+                paintByPath.set(path, m);
+            }
+            return m;
+        };
+        // THE PER-ENTRY BBOX (stroke 78): the export's THIRD arm —
+        // [x, y, w, h] pixels, the bbox-canvas leaf's drawn rectangle.
+        // Malformed refuses LOUD (a drifted bag is drift, never a skip);
+        // absent falls to the scope, then the renderer default.
+        const entryBbox = (raw) => {
+            if (raw === undefined || raw === null)
+                return undefined;
+            if (!Array.isArray(raw) || raw.length !== 4) {
+                throw new Error(`maskT1: an export bbox must be [x, y, w, h] pixels — got ${JSON.stringify(raw).slice(0, 60)}`);
+            }
+            const quad = raw.map(Number);
+            if (quad.some((v) => !Number.isFinite(v))) {
+                throw new Error(`maskT1: an export bbox needs four finite numbers — got ${JSON.stringify(raw).slice(0, 60)}`);
+            }
+            return { x: quad[0], y: quad[1], width: quad[2], height: quad[3] };
+        };
+        const n = Math.min(exports.length, kinds.length); // zip: the shorter arm wins
+        for (let i = 0; i < n; i++) {
+            const trip = exports[i];
+            const name = trip[0];
+            const payload = trip[1];
+            const kind = kinds[i];
+            if (kind === 'paint') {
+                // per-entry first (the draw's own PNG), the lane-global paint
+                // second (the studio flat-mode contract stays)
+                const path = typeof payload === 'string' && payload !== '' ? payload : (p.paint_mask ?? '');
+                if (path === '') {
+                    throw new Error(`maskT1: paint export '${name}' needs a payload — the drawn PNG is the mask`);
+                }
+                save(loadPaint(path), `mask_${name}`);
+                continue;
+            }
+            let conditioning;
+            if (kind !== 'sam2' && payload) {
+                // the text lane rides EVEN under scope (boxes to segment within
+                // + the vocabulary) — a scope never silently drops the prompt.
+                // sam2 exports skip it (their payload is the detector labels
+                // word — the detector proposes, SAM2 refines, never CLIP).
+                conditioning = clipCond(payload);
+            }
+            // THE PER-ENTRY BOX (stroke 78): the export's OWN third arm —
+            // the card-wide scope_bbox is the PRIMARY's box and never leaks
+            // into an export (an export without its own box runs unscoped).
+            const bboxes = entryBbox(trip[2]);
+            // THE PER-ENTRY TUNE (stroke 95): the export's OWN fourth arm.
+            const tune = entryTune(trip[3]);
+            if (kind === 'sam2') {
+                if (typeof payload !== 'string' || payload === '') {
+                    throw new Error(`maskT1: sam2 export '${name}' needs labels (a detector class word — the card refuses empty)`);
+                }
+                const sel = sam2detect(payload, bboxes ? { x: bboxes.x, y: bboxes.y, width: bboxes.width, height: bboxes.height } : undefined, tune);
+                save(sel.mask, `mask_${name}`, tune?.dilation);
+                continue;
+            }
+            const sel = detect(conditioning, bboxes, tune);
+            save(sel, `mask_${name}`, tune?.dilation);
+        }
+        // THE ORDERED UNION CHAIN (stroke 78 — the ordered-draw law): a
+        // draw STACKS — each payload unions onto the running mask (the
+        // previous outputs), in array order, one composite per hop; the
+        // terminal mask saves as combined_union. Replaces nothing — the
+        // single-payload boolean arm below keeps the flat-mode contract.
+        const paintChain = p.paint_masks;
+        if (paintChain !== undefined) {
+            if (!Array.isArray(paintChain) || paintChain.some((e) => typeof e !== 'string')) {
+                throw new Error('maskT1: paint_masks must be an array of payload paths (the ordered draw stack)');
+            }
+            if (primaryMask === null && paintChain.length > 0) {
+                throw new Error('maskT1: paint_masks stacks ONTO a mask — add a standalone source (sam2/sam3) first');
+            }
+            if (paintChain.length > 0 && primaryMask !== null) {
+                let acc = dilate(primaryMask);
+                for (const path of paintChain) {
+                    if (path === '')
+                        continue;
+                    acc = g.node('MaskComposite', {
+                        destination: acc,
+                        source: loadPaint(path),
+                        x: 0,
+                        y: 0,
+                        operation: 'add',
+                    }).out(0);
+                }
+                save(acc, 'mask_combined_union');
+            }
+        }
+        // paint unions into combined (flat-mode export_paint contract —
+        // the global payload's mask, ONE hop)
+        if (p.union_paint_into_combined && primaryMask) {
+            const globalPath = (p.paint_mask ?? '');
+            if (globalPath !== '') {
+                const combined = g.node('MaskComposite', {
+                    destination: dilate(primaryMask), // a SECOND GrowMask on the primary under union
+                    source: loadPaint(globalPath),
+                    x: 0,
+                    y: 0,
+                    operation: 'add',
+                }).out(0);
+                save(combined, 'mask_combined_union');
+            }
+        }
+        // ── the box manifest (drawn) — the instance readback ──
+        if (exportBoxes && rtdetrBoxes) {
+            const drawn = g.node('DrawBBoxes', { bboxes: rtdetrBoxes, image: img() });
+            return g.node('SaveImage', { images: drawn.out(0), filename_prefix: `${prefix}/detect_boxes` }).out(0);
+        }
+        // no primary and no export is refused upstream (the admission law),
+        // so a composed lane always has a mask handle to declare
+        return saved ?? primaryMask ?? img();
+    }
+};
+//# sourceMappingURL=actions.js.map

package/lib/index.d.ts

@@ -0,0 +1,26 @@
+import type { Plugin } from "@deepseek-ai/cordis";
+import type { ModelDecl } from '@melite/comfyui-card-kit/model-contract';
+import type { ProvisionRow } from '@melite/comfyui-card-kit/model-contract';
+
+
+
+
+
+
+
+
+
+export declare const PROVISIONS: ProvisionRow[];
+
+
+
+
+
+
+
+export declare const DETECTOR_PROVISIONS: ProvisionRow[];
+export declare const DECL: ModelDecl;
+export declare const family: Plugin;
+export { select, parseMaskLaneFacts, MASK_WEIGHTS, type MaskLaneFacts, type MaskLaneParams } from "./actions.js";
+export { family as default };
+//# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -0,0 +1,109 @@
+import { IMPACT_DETECTOR_PROVISIONS } from "@melite/comfyui-card-kit";
+import { select } from "./actions.js";
+
+
+
+
+
+
+
+
+
+export const PROVISIONS = [
+    {
+        
+        // existed since stroke ~40 but the weight was NEVER fetched —
+        // the engine silently dropped the whole mask arm). The official
+        // ComfyUI conversion.
+        name: "sam3.1_multiplex_fp16.safetensors",
+        url: "https://huggingface.co/Comfy-Org/sam3.1/resolve/main/checkpoints/sam3.1_multiplex_fp16.safetensors",
+        folder: "checkpoints",
+        sha256: "9ba99c92703c2e8b4f47de2d34a539bb8e18923049e238b780d70dbe6368eb03",
+        size_bytes: 1745546848,
+    },
+    {
+        name: "rt_detr_v4-x-hgnet_fp32.safetensors",
+        url: "https://huggingface.co/Comfy-Org/SDPose/resolve/main/diffusion_models/rt_detr_v4-x-hgnet_fp32.safetensors",
+        folder: "diffusion_models",
+        sha256: "1ba4a7794c2f8b176327c887ba38fbe0f977049cbef149960288aa923d0239f3",
+        size_bytes: 247790660,
+    },
+    {
+        name: "sam2.1_hiera_large.pt",
+        url: "https://huggingface.co/facebook/sam2.1-hiera-large/resolve/main/sam2.1_hiera_large.pt",
+        folder: "sams",
+        sha256: "2647878d5dfa5098f2f8649825738a9345572bae2d4350a2468587ece47dd318",
+        size_bytes: 898083611,
+    },
+    ...IMPACT_DETECTOR_PROVISIONS,
+];
+
+
+
+
+
+
+
+export const DETECTOR_PROVISIONS = [...IMPACT_DETECTOR_PROVISIONS];
+// THE TOOL FAMILY (the F1 shape): a selection tool, not a generative
+// model — `unoffered: true` registers the atom (the actions admission
+// gate runs at boot; the card's declaredAction binding resolves
+// against it) while serving no catalog row, so no model dropdown
+// gains a selection tool as a pickable base. The family id is
+// mask-select, NOT the card's id — the h3 pattern (family h3, card
+// h3-timeline): the card's id must keep resolving to the CARD (the
+// form-spec door asks the models seat first, and a family key
+// shadows the card arm — discovery.spec's mask envelope wall catches
+// exactly that), and the bench plane keeps the self-naming strip for
+// era rows. The three weights are the family's constants (actions.ts
+// MASK_WEIGHTS — the LANE_FILES pattern), so the row carries no
+// lane_inputs. ONE variant, ONE address, no cells: the family's id
+// is its own route — and its six weights DOWNLOAD through the family
+// provisions above, like every other model (no separate
+// card-provision behavior).
+export const DECL = {
+    "id": "mask-select",
+    "label": "Mask",
+    "description": "The mask studio's selection lane — SAM3 CLIP/RT-DETR detection, the SAM2 impact-pack arm, and paint exports, as one declared action the mask card binds.",
+    "genre": "image",
+    "unoffered": true,
+    "provisions": PROVISIONS,
+    "variants": [
+        {
+            "id": "select",
+            "label": "Select",
+            "group": "",
+            "route": "mask-select",
+            "cells": [],
+        },
+    ],
+    
+    // axes — the anny shape. The undeclared 'Variant' literal the
+    
+    // solo category the canon gives the one-row family.
+    "variant_groups": [],
+    // THE FAMILY DOOR (the atom vocabulary, stroke 0): the select
+    // action's facts parse runs over the family row and every variant
+    // merge AT REGISTRATION — here it closes over the family's own
+    // weight constants (an empty row is the family's whole truth).
+    "actions": [select],
+};
+export const family = {
+    name: "family-mask",
+    inject: ["models"],
+    apply(ctx) {
+        ctx.effect(() => ctx.models.registerFamily(DECL));
+    },
+};
+// The family's offered actions (the atom vocabulary): the select
+// segment the mask card binds. The card imports this beside the DECL
+// — the family's whole offer, one face. PROVISIONS rides too: the
+// card serves the family's rows to its arm-weight gate (the
+// provisions-identity pin, image/mask card.spec).
+export { select, parseMaskLaneFacts, MASK_WEIGHTS } from "./actions.js";
+// The Loader-row face: DSH loads plugin rows by bare specifier and
+// unwraps `exports.default ?? exports` (vendor/cordis_plugins/loader
+// unwrapExports) — the default export IS the row-loadable plugin. The
+// named `family` stays the library face (engine loadFamilies).
+export { family as default };
+//# sourceMappingURL=index.js.map