feat: add texture delight generation option (#8)

* feat: add texture delight generation option

* docs: clarify public CLI login guidance

Author: ElgoogUdiab

CONTRIBUTING.md

@@ -33,9 +33,9 @@ to `packages/cli/dist`. Tests exercise the compiled JavaScript. The build copies
 contract JSON into the artifact; consumers do not need TypeScript or install
 scripts. Do not commit `dist`.
 
-ESLint and Prettier follow the Hyper3D backend configuration: 80-column formatting,
+ESLint and Prettier enforce 80-column formatting,
 single quotes, trailing commas, sorted import groups, unused-import checks and
-type-aware promise rules. NestJS-specific rules do not apply to this CLI.
+type-aware promise rules.
 `npm run lint:fix` fixes lint issues; `npm run format:check` checks formatting
 without changing files. Tests and maintenance scripts are linted as JavaScript.
 

README.md

@@ -61,18 +61,22 @@ hyper3d generate --prompt "a ceramic teapot" --format glb
 # From one image
 hyper3d generate --image ./reference.png
 
+# For reference images with highly reflective surfaces
+hyper3d generate --image ./reference.png --texture-delight
+
 # From multiple views, with an optional description
 hyper3d generate --image ./front.png --image ./side.jpg --prompt "a ceramic teapot"
 ```
 
 Provide a prompt, one to five images, or both. Generation options:
 
-| Option        | Accepted values                                                | Default when omitted         |
-| ------------- | -------------------------------------------------------------- | ---------------------------- |
-| `--tier`      | `Gen-2.5-Medium`, `Gen-2.5-High`, `Gen-2.5-Extreme-Low`        | `Gen-2.5-Medium`             |
-| `--mesh-mode` | `Raw`, `Quad`                                                  | `Raw`                        |
-| `--format`    | `glb`, `usdz`, `fbx`, `obj`, `stl`                             | `glb`                        |
-| `--quality`   | Target polygon count: Raw `500–1,000,000`; Quad `1,000–50,000` | Raw `500,000`; Quad `18,000` |
+| Option              | Accepted values                                                         | Default when omitted         |
+| ------------------- | ----------------------------------------------------------------------- | ---------------------------- |
+| `--tier`            | `Gen-2.5-Medium`, `Gen-2.5-High`, `Gen-2.5-Extreme-Low`                 | `Gen-2.5-Medium`             |
+| `--mesh-mode`       | `Raw`, `Quad`                                                           | `Raw`                        |
+| `--format`          | `glb`, `usdz`, `fbx`, `obj`, `stl`                                      | `glb`                        |
+| `--quality`         | Target polygon count: Raw `500–1,000,000`; Quad `1,000–50,000`          | Raw `500,000`; Quad `18,000` |
+| `--texture-delight` | Flag: enable texture de-lighting for highly reflective reference images | `false`                      |
 
 Defaults are applied by the server. The response includes a generation ID; use
 it in place of `<generation-id>` to check progress and retrieve the result:

docs/architecture.md

@@ -3,9 +3,8 @@
 ## Authentication and CIMD
 
 The CLI uses OAuth Device Flow for every interactive login. Its public CIMD
-client ID is `https://hyper3d.ai/oauth_cimd/cli.json`. Deploy the JSON in
-`oauth_cimd/cli.json` at that exact URL, anonymously with
-`Content-Type: application/json`. It declares Device Flow and refresh-token
+client ID is `https://hyper3d.ai/oauth_cimd/cli.json`. The public metadata declares
+Device Flow and refresh-token
 grants, with empty `redirect_uris` and `response_types`. No client secret or
 localhost callback is used. Publishing CIMD does not publish the CLI to npm.
 
@@ -17,18 +16,14 @@ npm run cli -- auth logout
 ```
 
 Login prints a code and opens the returned `verification_uri_complete` URL.
-The backend then redirects the browser to
-`https://hyper3d.ai/workspace/oauth/device?interaction=<handle>`.
-The CLI uses the returned verification URL, not a hardcoded frontend URL.
+The CLI follows the returned verification URL.
 The user confirms that the browser code matches the terminal, then authorizes
 the CLI. `--no-browser` only prints the link/code for SSH or another device.
 Failure to launch the browser leaves the same login waiting for manual approval.
 The CLI polls until success, denial or device-code expiry and handles polling
 backoff. Ctrl+C cancels login. Login never falls back to authorization-code/PKCE.
 
-Deploy the backend Device Flow support, frontend device confirmation page and
-updated CIMD, and add the exact client ID to `grant.device_flow_client_ids`
-before using this against production. The CLI fails explicitly when the server
+The CLI fails explicitly when the service
 does not advertise Device Flow. Existing MCP clients retain their own login flows.
 
 The SDK handles OAuth discovery, resource validation and subsequent token
@@ -53,8 +48,8 @@ the default output says the user is not authenticated; `--output json` returns
 explicitly rather than reporting a verified login.
 
 The CLI explicitly requests `rodin:generate rodin:read account:read offline_access`;
-it never requests every scope advertised by discovery. Deploy backend support for
-`account:read` and the updated official CIMD before using account lookup. Existing
+it never requests every scope advertised by discovery. Account lookup requires
+the `account:read` permission. Existing
 users must run `hyper3d auth login` again to grant the new permission. Refreshing
 an older grant does not add scopes. Existing MCP tool permissions and the public
 MCP discovery scope list remain unchanged.
@@ -99,7 +94,7 @@ integer timeout in seconds. It automatically chains wait-tool calls of at most
 
 Every MCP HTTP request includes `X-Hyper3D-CLI-Version`, read from the CLI's
 package version, matching the version sent in MCP initialization `clientInfo`.
-This lets the stateless backend read the CLI version on individual tool calls;
+This identifies the CLI version on individual tool calls;
 the OAuth `client_id` remains unchanged.
 
 ## CLI layers
@@ -121,8 +116,8 @@ the live server schema.
 
 `src/base_schema.json` is the single bundled reference snapshot of the public
 production tool list. It contains 7 tools and their input/output schemas, without
-schema versions or implementation adapters. Backend compatibility is handled by
-the backend; the CLI has one implementation of each operation.
+schema versions or implementation adapters. The CLI has one implementation of
+each operation.
 
 Actual requests are validated against the live server schema. Differences from
 the base input schema warn but do not reject input accepted by the server.

docs/releasing.md

@@ -100,5 +100,5 @@ do not republish or move an existing tag. An already-existing stable tag also
 blocks publication before npm is changed. A rerun of a beta workflow gets a new
 attempt suffix, provided its planned version is still above main and latest.
 
-Before releasing, verify the deployed Device Flow and official CIMD client metadata.
-See [architecture.md](architecture.md) for the backend integration contract.
+Before releasing, verify CLI login using Device Flow and the public CIMD client metadata.
+See [architecture.md](architecture.md) for authentication and compatibility details.

package-lock.json

@@ -61,18 +61,22 @@ hyper3d generate --prompt "a ceramic teapot" --format glb
 # From one image
 hyper3d generate --image ./reference.png
 
+# For reference images with highly reflective surfaces
+hyper3d generate --image ./reference.png --texture-delight
+
 # From multiple views, with an optional description
 hyper3d generate --image ./front.png --image ./side.jpg --prompt "a ceramic teapot"
 ```
 
 Provide a prompt, one to five images, or both. Generation options:
 
-| Option        | Accepted values                                                | Default when omitted         |
-| ------------- | -------------------------------------------------------------- | ---------------------------- |
-| `--tier`      | `Gen-2.5-Medium`, `Gen-2.5-High`, `Gen-2.5-Extreme-Low`        | `Gen-2.5-Medium`             |
-| `--mesh-mode` | `Raw`, `Quad`                                                  | `Raw`                        |
-| `--format`    | `glb`, `usdz`, `fbx`, `obj`, `stl`                             | `glb`                        |
-| `--quality`   | Target polygon count: Raw `500–1,000,000`; Quad `1,000–50,000` | Raw `500,000`; Quad `18,000` |
+| Option              | Accepted values                                                         | Default when omitted         |
+| ------------------- | ----------------------------------------------------------------------- | ---------------------------- |
+| `--tier`            | `Gen-2.5-Medium`, `Gen-2.5-High`, `Gen-2.5-Extreme-Low`                 | `Gen-2.5-Medium`             |
+| `--mesh-mode`       | `Raw`, `Quad`                                                           | `Raw`                        |
+| `--format`          | `glb`, `usdz`, `fbx`, `obj`, `stl`                                      | `glb`                        |
+| `--quality`         | Target polygon count: Raw `500–1,000,000`; Quad `1,000–50,000`          | Raw `500,000`; Quad `18,000` |
+| `--texture-delight` | Flag: enable texture de-lighting for highly reflective reference images | `false`                      |
 
 Defaults are applied by the server. The response includes a generation ID; use
 it in place of `<generation-id>` to check progress and retrieve the result:

packages/cli/README.md

@@ -1,6 +1,6 @@
 {
   "name": "@hyper3d/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Hyper3D CLI backed by MCP",
   "repository": {
     "type": "git",

packages/cli/package.json

@@ -203,7 +203,7 @@ async function discoverDeviceFlow(
     !metadata.grant_types_supported?.includes(DEVICE_GRANT_TYPE)
   )
     throw new Error(
-      'The server does not advertise Device Flow. Deploy and enable the backend before logging in.',
+      'The server does not advertise Device Flow. Contact the service administrator for login support.',
     );
   if (!metadata.token_endpoint) throw new Error('Missing OAuth token endpoint');
   secureUrl(metadata.token_endpoint);

packages/cli/src/auth.ts

@@ -202,7 +202,7 @@
     {
       "name": "rodin_generate",
       "title": "Generate a Rodin 3D model",
-      "description": "Start a Rodin Gen-2.5 generation from a non-empty prompt, one or more reference images, or both. At least one of prompt or reference_upload_ids is required. For image references in ChatGPT Chat, first call rodin_import_images and pass the returned uploads[].upload_id values as reference_upload_ids in order. The presigned upload workflow uses rodin_create_uploads followed by successful HTTP PUT uploads. This consumes credits. The response includes display_url; present that URL only after the generation completes. If this call times out, do not retry it automatically; ask the user to check Hyper3D Mine.",
+      "description": "Start a Rodin Gen-2.5 generation from a non-empty prompt, one or more reference images, or both. At least one of prompt or reference_upload_ids is required. For image references in ChatGPT Chat, first call rodin_import_images and pass the returned uploads[].upload_id values as reference_upload_ids in order. The presigned upload workflow uses rodin_create_uploads followed by successful HTTP PUT uploads. texture_delight defaults to false; setting it to true is recommended when reference images contain highly reflective surfaces. This consumes credits. The response includes display_url; present that URL only after the generation completes. If this call times out, do not retry it automatically; ask the user to check Hyper3D Mine.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -232,6 +232,11 @@
             "enum": ["Gen-2.5-Medium", "Gen-2.5-High", "Gen-2.5-Extreme-Low"],
             "default": "Gen-2.5-Medium"
           },
+          "texture_delight": {
+            "type": "boolean",
+            "default": false,
+            "description": "Enable texture de-lighting. Defaults to false; recommended when reference images contain highly reflective surfaces."
+          },
           "quality_override": {
             "type": "integer",
             "minimum": 500,

packages/cli/src/base_schema.json

@@ -103,6 +103,10 @@ cli
     'Generation tier: Gen-2.5-Medium, Gen-2.5-High, Gen-2.5-Extreme-Low (server default: Gen-2.5-Medium)',
   )
   .option('--mesh-mode <mode>', 'Mesh mode: Raw, Quad (server default: Raw)')
+  .option(
+    '--texture-delight',
+    'Enable texture de-lighting; recommended for highly reflective reference images (server default: false)',
+  )
   .option(
     '--format <format>',
     'Geometry format: glb, usdz, fbx, obj, stl (server default: glb)',