dominus-cli 0.5.2 → 0.5.4

package/dist/index.js

@@ -678,6 +678,7 @@ These are built-in lessons that ship with Dominus. Follow them exactly.
 - Single 3D part \u2192 \`create_part\`
 - Many 3D parts (tree, building, vehicle) \u2192 \`build_multiple\` with \`groupName\`
 - Full UI tree \u2192 \`create_ui\` (one call, never loop \`insert_instance\` for UI)
+- **Convert/export existing UI \u2192 \`serialize_ui\`** (NOT get_descendants_properties)
 - Adjusting an existing instance \u2192 \`set_properties\` (not \`run_code\`)
 - Anything exotic or procedural \u2192 \`run_code\` as last resort
 
@@ -685,6 +686,23 @@ These are built-in lessons that ship with Dominus. Follow them exactly.
 - After a build, call \`get_explorer\` or \`get_selection\` to confirm the tree looks right.
 - After editing a script, read it back.
 - After \`run_code\`, check \`get_output\` for errors.
+
+### serialize_ui \u2014 the RIGHT tool for UI conversion
+- **Use \`serialize_ui\` when converting existing UI to Roact/React/Fusion components.** It returns a minimal JSON tree with only non-default properties, already in JSON-friendly formats.
+- **Do NOT use \`get_descendants_properties\` for UI conversion** \u2014 it returns a flat list with ~50+ properties per instance (including read-only, deprecated, nil, and default values), which bloats context and confuses conversion.
+- \`serialize_ui\` output maps 1:1 to \`create_ui\` input \u2014 you can round-trip UI through it.
+- The tree structure preserves parent-child hierarchy, so Roact/React children mapping is direct.
+
+### UI \u2192 Roact/React conversion cheat-sheet
+- \`serialize_ui\` path \u2192 JSON tree \u2192 map each node to \`Roact.createElement(ClassName, props, childrenDict)\`
+- UDim2 arrays \`[xS, xO, yS, yO]\` \u2192 \`UDim2.new(xS, xO, yS, yO)\`
+- Color3 hex strings \u2192 \`Color3.fromHex("#RRGGBB")\`
+- Vector2 arrays \u2192 \`Vector2.new(x, y)\`
+- UDim arrays \u2192 \`UDim.new(s, o)\`
+- Enum strings like \`"Center"\` \u2192 \`Enum.TextXAlignment.Center\`
+- FontFace \u2192 \`Font.new(family, weight, style)\`
+- UI modifiers (UICorner, UIStroke, UIGradient, UIListLayout, UIPadding) are CHILDREN not props
+- Use instance Name as dictionary key in children table
 `;
   }
 });
@@ -1198,7 +1216,7 @@ var init_get_descendants_properties = __esm({
     init_protocol();
     tool6 = {
       name: "get_descendants_properties",
-      description: "Easily get all descendants of a UI instance (or any instance) and all of their properties.",
+      description: "Easily get all descendants of a UI instance (or any instance) and all of their properties. By default uses compact mode which strips read-only, nil, deprecated, and default-valued properties to keep responses small.",
       parameters: {
         type: "object",
         properties: {
@@ -1206,6 +1224,10 @@ var init_get_descendants_properties = __esm({
             type: "string",
             description: 'Full instance path (e.g., "Workspace.Part", "StarterGui.ScreenGui")'
           },
+          compact: {
+            type: "boolean",
+            description: "When true (default), strips read-only, nil, deprecated, and default-valued properties to massively reduce response size. Set to false for full property dump."
+          },
           outputFile: {
             type: "string",
             description: "Optional file path to write the JSON result to, useful for very large trees where context limits apply."
@@ -1217,9 +1239,10 @@ var init_get_descendants_properties = __esm({
         if (!ctx.isStudioConnected()) {
           return { success: false, error: "Studio is not connected" };
         }
+        const compact = params.compact !== false;
         const response = await ctx.sendToStudio(
           CliMsg.GET_DESCENDANTS_PROPERTIES,
-          { path: params.path },
+          { path: params.path, compact },
           1e3 * 60 * 5
           // 5 minute timeout since getting ALL descendants can take a very long time
         );
@@ -2623,14 +2646,15 @@ async function startMcpServer() {
   );
   mcp.tool(
     "get_descendants_properties",
-    "Easily get all descendants of a UI instance (or any instance) and all of their properties.",
+    "Easily get all descendants of a UI instance (or any instance) and all of their properties. By default uses compact mode which strips read-only, nil, deprecated, and default-valued properties to keep responses small.",
     {
       path: z.string().describe('Full instance path (e.g., "Workspace.Part", "StarterGui.ScreenGui")'),
+      compact: z.boolean().optional().default(true).describe("Strip noisy/default properties (default true). Set false for full dump."),
       outputFile: z.string().optional().describe("Optional file path to write to prevent limit errors/timeouts")
     },
-    async ({ path: path5, outputFile }) => {
+    async ({ path: path5, compact, outputFile }) => {
       assertConnected();
-      const res = await bridge.sendRequest(CliMsg.GET_DESCENDANTS_PROPERTIES, { path: path5, outputFile }, 1e3 * 60 * 5);
+      const res = await bridge.sendRequest(CliMsg.GET_DESCENDANTS_PROPERTIES, { path: path5, compact, outputFile }, 1e3 * 60 * 5);
       return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
     }
   );
@@ -2947,6 +2971,26 @@ async function startMcpServer() {
       return { content: [{ type: "text", text: JSON.stringify(res.payload, null, 2) }] };
     }
   );
+  mcp.tool(
+    "serialize_ui",
+    "Serialize an existing Roblox UI tree into a compact, create_ui-compatible JSON tree. This is the reverse of create_ui \u2014 reads any GUI instance and returns a declarative JSON tree with ClassName, Name, non-default properties (Color3 as hex, UDim2 as arrays, etc.), and Children. Perfect for: converting existing UI to Roact/React components, cloning/templating, understanding UI structure, or refactoring. Use this INSTEAD of get_descendants_properties when you need to recreate or convert UI.",
+    {
+      path: z.string().describe('Instance path to serialize (e.g. "StarterGui.MyScreenGui")'),
+      maxDepth: z.number().optional().default(50).describe("Maximum tree depth (default 50)")
+    },
+    async ({ path: path5, maxDepth }) => {
+      assertConnected();
+      const res = await bridge.sendRequest(
+        CliMsg.SERIALIZE_UI,
+        { path: path5, maxDepth },
+        1e3 * 60 * 2
+      );
+      if (!res.payload.success) {
+        return { content: [{ type: "text", text: `Error: ${res.payload.error ?? "Serialization failed"}` }] };
+      }
+      return { content: [{ type: "text", text: JSON.stringify(res.payload.tree, null, 2) }] };
+    }
+  );
   mcp.tool(
     "recall_memory",
     "Search persistent memory for facts about the current Roblox project",
@@ -4347,6 +4391,66 @@ GUI classes use DIFFERENT property types than 3D parts:
 - All enum properties from string names
 - Color3 from hex "#RRGGBB", "rgb(r,g,b)", or BrickColor name strings
 
+## Serializing & Converting Existing UI
+When the user asks to convert, export, recreate, or turn an existing UI into a React/Roact component:
+
+**Use \`serialize_ui\` \u2014 NOT \`get_descendants_properties\`.**
+\`serialize_ui\` returns a clean, minimal JSON tree with only non-default properties, values already in JSON-friendly formats (hex colors, UDim2 arrays, enum names), and a proper parent-child hierarchy. It's purpose-built for this exact workflow.
+
+\`get_descendants_properties\` returns a flat list with ALL properties (including read-only, defaults, deprecated) \u2014 it's much larger and harder to convert.
+
+### Roblox UI \u2192 Roact/React Conversion Workflow
+1. Call \`serialize_ui\` with the path (e.g. \`StarterGui.MyScreenGui.MyFrame\`)
+2. The result is a tree like:
+\`\`\`json
+{
+  "ClassName": "Frame", "Name": "MyFrame",
+  "Size": [0.5, 0, 0.3, 0], "BackgroundColor3": "#1a1a2e",
+  "Children": [
+    { "ClassName": "UICorner", "CornerRadius": [0, 8] },
+    { "ClassName": "TextLabel", "Name": "Title", "Text": "Hello",
+      "Size": [1, 0, 0.2, 0], "TextColor3": "#ffffff", "BackgroundTransparency": 1 }
+  ]
+}
+\`\`\`
+3. Convert to Roact/React-lua using these mappings:
+   - Each JSON node \u2192 \`Roact.createElement(ClassName, props, children)\` or \`React.createElement\`
+   - \`UDim2\` arrays \`[xS, xO, yS, yO]\` \u2192 \`UDim2.new(xS, xO, yS, yO)\`
+   - \`Color3\` hex \`"#RRGGBB"\` \u2192 \`Color3.fromHex("#RRGGBB")\`
+   - \`Vector2\` arrays \`[x, y]\` \u2192 \`Vector2.new(x, y)\`
+   - \`UDim\` arrays \`[s, o]\` \u2192 \`UDim.new(s, o)\`
+   - Enum strings \`"Center"\` \u2192 \`Enum.TextXAlignment.Center\` (resolve the full enum path)
+   - \`Children\` array \u2192 child elements table
+   - UI modifiers (UICorner, UIStroke, UIGradient, UIListLayout, UIPadding, UIScale) \u2192 children of the parent element
+
+### Example Roact output:
+\`\`\`lua
+local function MyFrame()
+    return Roact.createElement("Frame", {
+        Size = UDim2.new(0.5, 0, 0.3, 0),
+        BackgroundColor3 = Color3.fromHex("#1a1a2e"),
+    }, {
+        Corner = Roact.createElement("UICorner", {
+            CornerRadius = UDim.new(0, 8),
+        }),
+        Title = Roact.createElement("TextLabel", {
+            Size = UDim2.new(1, 0, 0.2, 0),
+            Text = "Hello",
+            TextColor3 = Color3.fromHex("#ffffff"),
+            BackgroundTransparency = 1,
+        }),
+    })
+end
+\`\`\`
+
+### Key rules for conversion:
+- Use the instance \`Name\` as the dictionary key in the children table
+- UI modifiers (UICorner, UIStroke, etc.) are CHILDREN, not props
+- Keep the exact property values from serialize_ui \u2014 don't guess or approximate
+- For Fusion: \`New "Frame" { Size = UDim2.new(...), [Children] = { ... } }\`
+- Preserve ZIndex ordering when relevant
+- FontFace objects \u2192 \`Font.new("rbxasset://fonts/families/...", Enum.FontWeight.Bold)\`
+
 ## ReflectionService
 The \`get_class_info\` tool queries Roblox's ReflectionService to return the complete API surface for any class:
 - All properties with their exact ValueType