@melite/3d-img-to-mesh 0.1.4-alpha → 0.1.5-pre-alpha

package/README.md

@@ -0,0 +1,38 @@
+---
+description: Image-to-mesh card that boards three mesh families — pixal3d, trellis2-native, and transfer_rig — plus the mesh studio client.
+kind: package-library
+---
+
+# @melite/3d-img-to-mesh
+
+`@melite/3d-img-to-mesh` is the image-to-mesh card. One card serves three families, each with its own declared action: `pixal3d` and `trellis2-native` run the `mesh` action (image in, mesh out); `transfer_rig` runs `transfer` (rig transfers between two GLBs). The cardPackages SSOT composes the card from `./card`; the browser studio rides `./client`.
+
+## Contract
+
+- `./card` — the card definition (`id: 'img-to-mesh'`). Family dispatch keys on `model.family ?? model.id`; an unbound family refuses loudly. Per-family requirements: pixal3d needs the `ComfyUI-MoGe` pack, transfer_rig needs `melite-autorig-nodes`, trellis2-native needs none; the card-level `requires` is the union. Flow seats: `input_image` (image), `rigged_glb` and `target_glb` (mesh) in; mesh out, bound to `Save3DAdvanced.0` or `SaveRiggedModel.0` per action. Autofill literals (RemeshMesh band/project_back, ImageCropToMask background/grow_mask, MoGeInference apply_mask/batch_size/force_projection/fov_x_degrees) ride the compose; `remesh_qef`, `remesh_drop_inverted`, `remesh_drop_enclosed`, and `remesh_fix_poles` are card params.
+- `./client` — `ImgToMeshStudio`, a DeclarativeStudio registration exposing the `input` and `generation` stages with the mesh preview; the plugin injects into `slots`.
+- `.` — the row-mounted host face; it registers nothing.
+- `./package.json` — the manifest.
+
+## Model Experience
+
+### Request context and condition
+
+A run conditions the mesh graph only when the card composes; the package ships no agent tool face.
+
+#### What the model sees
+
+The active family's mesh model receives `input_image` plus the gated card params; the transfer action receives both GLBs.
+
+#### Token effect
+
+zero-direct — the package contributes no prompt or schema to any language-model context.
+
+#### KV Cache effect
+
+independent — nothing here appends to or reshapes a session cache.
+
+## Known Limitations and Deferred Work
+
+- **Per-family surfaces differ** — only pixal3d and transfer_rig carry pack requirements today; a new family must declare both its action and its slice.
+- **Studio exposure is fixed** — `ImgToMeshStudio` folds the input and generation stages; other stages are not exposed yet.

package/lib/card.d.ts

@@ -1,6 +1,5 @@
-import type { Context } from '@deepseek-ai/cordis';
-import type { ModelFacts } from '@melite/comfyui-card-kit/facts';
-import type { GraphBuilder } from '@melite/comfyui-card-kit/graph';
+import type { Context } from '@melite/comfyui-card-kit/card-definition';
+import { type ActionBinding as Binding } from '@melite/comfyui-card-kit';
 export declare const inject: string[];
 export declare const identity: {
     label: string;
@@ -8,7 +7,6 @@ export declare const identity: {
     genre: string;
     icon: string;
 };
-export type Binding = (p: Record<string, unknown>, model: ModelFacts, g: GraphBuilder, runId: string) => void;
 export declare const ACTION_BINDINGS: Record<string, Binding>;
 export declare function apply(ctx: Context): void;
 //# sourceMappingURL=card.d.ts.map

package/lib/card.js

@@ -1,11 +1,13 @@
 import z from '@deepseek-ai/schemastery';
-import { declaredAction, instantiateAction, MESH_RESOLUTIONS, MESH_BG_MODES, MESH_PIXAL_FOVS, MESH_ATLAS_SIZES, MESH_AO_SIZES, MESH_NORMAL_SIZES } from '@melite/comfyui-card-kit';
+import { declaredAction, instantiateAction, MESH_RESOLUTIONS, MESH_PIXAL_FOVS, MESH_ATLAS_SIZES, MESH_AO_SIZES, MESH_NORMAL_SIZES } from '@melite/comfyui-card-kit';
 import { DECL as pixal3dDecl } from '@melite/models-pixal3d';
 import { DECL as trellis2NativeDecl } from '@melite/models-trellis2-native';
 import { DECL as transferRigDecl } from '@melite/models-transfer_rig';
 import { SAMPLERS, SCHEDULERS, vocabulary } from '@melite/comfyui-card-kit/vocab';
 import { bag } from '@melite/contracts/extraKeys';
-import { gatedResolve } from '@melite/comfyui-cordis';
+import { ComposeRefusal } from '@melite/comfyui-card-kit/errors';
+import { seedExtra } from '@melite/comfyui-card-kit/fields';
+import { callableSchema, gatedResolve } from '@melite/comfyui-card-kit/admission';
 const schema = z.object({
     // Ride keys (no .default — the compose-door cascade overlays model
     // defaults, then explicit params): input_image is required; the
@@ -14,16 +16,15 @@ const schema = z.object({
     // lift call never names them and a rig call names both. Bare
     // z.string() is the image-gen prompt precedent (optional at parse,
     // refused loud at compose).
-    input_image: z.string().role('path').description("Source image").extra('extra', bag({ order: 0, group: "input", columns: 1, tooltip: "One clear object, tight framing. Background is removed automatically (birefnet) unless bg_removal=off.", required: true, families: ['pixal3d', 'trellis2-native'], wtype: 'image', })),
+    input_image: z.string().role('path').description("Source image").extra('extra', bag({ order: 0, group: "input", columns: 1, tooltip: "One clear object, tight framing — the lane crops it to a square and conditions on it directly.", required: true, families: ['pixal3d', 'trellis2-native'], wtype: 'image', })),
     rigged_glb: z.string().role('path').description("Rigged source GLB").extra('extra', bag({ order: 0, group: "input", columns: 1, tooltip: "The SOMA-rigged clean mesh — JOINTS_0/WEIGHTS_0 + armature. The rig donor.", families: ['transfer_rig'], wtype: 'mesh' })),
     target_glb: z.string().role('path').description("Target GLB").extra('extra', bag({ order: 1, group: "input", columns: 1, tooltip: "The clothed mesh — geometry + textures, no rig. Receives the rig.", families: ['transfer_rig'], wtype: 'mesh' })),
-    seed: z.number().description("Seed").step(1).extra('extra', bag({ order: 1, group: "input", width: 1, tooltip: "Same seed + image = same mesh take.", families: ['pixal3d', 'trellis2-native'] })),
+    seed: z.number().description("Seed").step(1).extra('extra', bag(seedExtra({ order: 1, group: 'input', width: 1, tooltip: 'Same seed + image = same mesh take.', families: ['pixal3d', 'trellis2-native'] }))),
     // Select knobs coerce wire strings at compose (the skin map_size
     // precedent) — enum hints ride extra.options, never validation.
     resolution: vocabulary(MESH_RESOLUTIONS).description("Resolution").extra('extra', bag({ order: 0, group: "generation", width: 1, tooltip: "Upsample target (the live node accepts 1024–2048; the family routes serve 1024 and 1536). All tiers run the full official chain — upsample + both texture passes + remesh tail.", families: ['pixal3d', 'trellis2-native'], wtype: 'select' })),
     steps: z.number().description("Steps").min(4).max(60).step(1).extra('extra', bag({ order: 1, group: "generation", width: 1, tooltip: "STRUCTURE stage steps (the lift). Shape + texture stages ride their own knobs in the Stage section.", families: ['pixal3d', 'trellis2-native'], wtype: 'number' })),
     cfg: z.number().description("CFG").min(1).max(15).step(0.5).extra('extra', bag({ order: 2, group: "generation", width: 1, tooltip: "Structure-stage guidance. 7.5 is the official template calibration (2026-09-06: the 3.0 default sampled the coarse shape at under half guidance — blobby trash out of the box). Lower runs looser.", families: ['pixal3d', 'trellis2-native'] })),
-    bg_removal: vocabulary(MESH_BG_MODES).description("Background removal").extra('extra', bag({ order: 3, group: "generation", width: 1, tooltip: "auto/on: birefnet cuts the background (recommended). off: feed a pre-cleaned or alpha-cut image straight to conditioning.", families: ['pixal3d', 'trellis2-native'], wtype: 'select' })),
     camera_fov: vocabulary(MESH_PIXAL_FOVS).description("Camera FoV").extra('extra', bag({ order: 4, group: "generation", width: 1, tooltip: "Pixal3D only — per-image horizontal FoV feeding the camera transform matrix. auto: MoGeInference estimates from the source image (recommended); a literal degree value skips MoGe (operator-vouched camera, e.g. calibrated).", families: ['pixal3d'], wtype: 'select' })),
     shape_steps: z.number().description("Shape steps").min(4).max(60).step(1).extra('extra', bag({ order: 0, group: "stage", width: 1, tooltip: "Shape-stage steps. 20 is the official template calibration.", families: ['pixal3d', 'trellis2-native'], wtype: 'number' })),
     shape_cfg: z.number().description("Shape CFG").min(1).max(15).step(0.5).extra('extra', bag({ order: 1, group: "stage", width: 1, tooltip: "Shape-stage guidance. 7.5 is the official template calibration.", families: ['pixal3d', 'trellis2-native'] })),
@@ -61,12 +62,7 @@ const schema = z.object({
     // never a declared knob, and compose never reads it: prefixes are
     // family constants below).
 });
-/** The schema's callable face — ONE cast serving both seams (the
- *  registration's schema carrier and the compose strict resolve's
- *  judge): schemastery schemas are callable (Schema.resolve) but
- *  carry a typed data parameter, while both card-seam consumers
- *  take unknown. */
-const schemaFn = schema;
+const schemaFn = callableSchema(schema);
 export const inject = ['comfyui'];
 
 // identity ring; the card owns its label/description/genre/icon).
@@ -76,6 +72,11 @@ export const identity = {
     genre: '3d',
     icon: 'box',
 };
+// THE FAMILY BINDINGS (the atom vocabulary, stroke 3): every
+// boarded family's declared action, keyed by the row's family
+// address — the id-switch dispatch died with them. A family-less
+// row (the declared fallback) rides the legacy lane arms below —
+// never a silent second copy.
 export const ACTION_BINDINGS = {
     [pixal3dDecl.id]: (p, model, g, runId) => void instantiateAction(declaredAction(pixal3dDecl, 'mesh'), p, model, g, runId),
     [trellis2NativeDecl.id]: (p, model, g, runId) => void instantiateAction(declaredAction(trellis2NativeDecl, 'mesh'), p, model, g, runId),
@@ -146,6 +147,20 @@ export function apply(ctx) {
             // their rows), fills defaults, passes undeclared keys through
             // inert. The composer's reads below are reads of the GATED doc.
             const doc = gatedResolve('img-to-mesh', schemaFn, ['model', 'input_image', 'rigged_glb', 'target_glb'], p);
+            // THE PAIRED GLB LANE (round-22 compose audit Q4b, EXHAUSTIVE-WHEN):
+            // rigged_glb and target_glb are one paired transfer lane — both or
+            // neither, on EVERY family. The lift arms ignore the pair, so a
+            // mixed state composed fine there and the producer walk then
+            // selected no output at all: zero outputs, silently. The mixed
+            // state refuses here, before any arm; the producer predicates
+            // stay exclusive on the states that remain reachable.
+            const riggedSet = String(doc.rigged_glb ?? '').trim() !== '';
+            const targetSet = String(doc.target_glb ?? '').trim() !== '';
+            if (riggedSet !== targetSet) {
+                throw new ComposeRefusal('bad-value', `card 'img-to-mesh': rigged_glb and target_glb are one paired transfer lane — ` +
+                    `${riggedSet ? "rigged_glb is set but target_glb is empty" : "target_glb is set but rigged_glb is empty"}; ` +
+                    `set both for the rig transfer, or neither for the image-to-mesh lift`);
+            }
             // The arm IS the family's declared action (runId rides the
             // signature; prefixes are family constants, not run-scoped,
             // not knobs).

package/lib/client.js

@@ -20,14 +20,30 @@ window.__ModuleLoader__.load({
 
 		
 
+
+
+
+
 		const SURFACE = (0, _melite_card_base_client.defineStudioDeclaration)({
 			model: "img-to-mesh",
 			expose: ["input", "generation"],
 			folds: {
-				stage: "Stage passes",
-				mesh: "Mesh",
-				bake: "Bake maps",
-				lab: "Lab (samplers & overrides)"
+				stage: {
+					title: "Stage passes",
+					icon: "branch"
+				},
+				mesh: {
+					title: "Mesh",
+					icon: "box"
+				},
+				bake: {
+					title: "Bake maps",
+					icon: "layers"
+				},
+				lab: {
+					title: "Lab (samplers & overrides)",
+					icon: "sliders"
+				}
 			},
 			preview: "mesh"
 		});

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-import type { Context } from '@deepseek-ai/cordis';
+import type { Context } from '@melite/comfyui-card-kit/card-definition';
 export declare const name = "@melite/3d-img-to-mesh";
 export declare const inject: string[];
 export declare function apply(_ctx: Context): void;

package/package.json

@@ -1,8 +1,8 @@
 {
-  "version": "0.1.4-alpha",
+  "version": "0.1.5-pre-alpha",
   "license": "SSPL-1.0",
   "type": "module",
-  "description": "the img-to-mesh card (the 3d lane) — one card one package: card.ts host face + ui/ studio + agents/ context",
+  "description": "the img-to-mesh card (the 3d lane) — one card one package: card.ts host face + agents/ context (no tool face, no ui/ — the view is constructed by @melite/card-base from the emission)",
   "exports": {
     ".": {
       "types": "./lib/index.d.ts",
@@ -20,15 +20,13 @@
     "@deepseek-ai/dsh-client-ui-renderer": "0.2.0-rc.1",
     "@deepseek-ai/schemastery": "3.18.4",
     "react": "^19.3.0",
-    "@melite-plugin/melite-run-wire": "0.1.4-alpha",
-    "@melite/comfyui-card-kit": "0.1.4-alpha",
-    "@melite/comfyui-cordis": "0.1.4-alpha",
-    "@melite/contracts": "0.1.4-alpha",
-    "@melite/models-pixal3d": "0.1.4-alpha",
-    "@melite/models-transfer_rig": "0.1.4-alpha",
-    "@melite/models-trellis2-native": "0.1.4-alpha",
-    "@melite/card-base": "0.1.4-alpha",
-    "@melite-plugin/3d": "0.1.4-alpha"
+    "@melite-plugin/melite-run-wire": "0.1.5-pre-alpha",
+    "@melite/card-base": "0.1.5-pre-alpha",
+    "@melite/comfyui-card-kit": "0.1.5-pre-alpha",
+    "@melite/contracts": "0.1.5-pre-alpha",
+    "@melite/models-pixal3d": "0.1.5-pre-alpha",
+    "@melite/models-transfer_rig": "0.1.5-pre-alpha",
+    "@melite/models-trellis2-native": "0.1.5-pre-alpha"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "*",