human2ai 0.1.2 → 0.1.4

package/schemas/composition-draft.schema.json

@@ -10,6 +10,7 @@
     { "if": { "required": ["activeStateId"] }, "then": { "required": ["states"] } }
   ],
   "properties": {
+    "plans": { "type": "array", "items": { "$ref": "#/$defs/compositionPlan" } },
     "activeStateId": { "type": "string", "minLength": 1 },
     "states": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/state" } },
     "layerOrder": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
@@ -78,6 +79,7 @@
           "aspect": { "enum": ["square", "free", "landscape", "portrait"] },
           "visualWeight": { "enum": ["auto", "high", "medium", "low", "decorative"] },
           "displayText": { "type": "string" },
+          "corners": { "$ref": "#/$defs/textCorners" },
           "isLightSource": { "type": "boolean" },
           "rotation": { "type": "number" },
           "width": { "type": "number", "exclusiveMinimum": 0 },
@@ -99,7 +101,11 @@
               "required": ["semanticType"]
             },
             "then": { "required": ["displayText"], "properties": { "isLightSource": { "const": false } } },
-            "else": { "not": { "required": ["displayText"] } }
+            "else": { "not": { "anyOf": [{ "required": ["displayText"] }, { "required": ["corners"] }] } }
+          },
+          {
+            "if": { "required": ["corners"] },
+            "then": { "properties": { "primitive": { "const": "quadrilateral" }, "aspect": { "const": "free" } } }
           }
         ]
       }
@@ -147,6 +153,461 @@
     }
   },
   "$defs": {
+    "compositionPlan": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "visible",
+        "type"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^plan-[a-zA-Z0-9-]+$"
+        },
+        "visible": {
+          "type": "boolean"
+        },
+        "axes": {
+          "enum": [
+            "both",
+            "horizontal",
+            "vertical"
+          ]
+        },
+        "x": {
+          "type": "number"
+        },
+        "y": {
+          "type": "number"
+        },
+        "rotation": {
+          "type": "number"
+        },
+        "scale": {
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
+        "mirrored": {
+          "type": "boolean"
+        },
+        "type": {
+          "enum": [
+            "thirds",
+            "golden-section",
+            "symmetry",
+            "golden-spiral",
+            "triangle",
+            "radial"
+          ]
+        },
+        "width": {
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
+        "height": {
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
+        "rayCount": {
+          "type": "integer",
+          "minimum": 2,
+          "maximum": 36
+        },
+        "spread": {
+          "type": "number",
+          "minimum": 1,
+          "maximum": 360
+        },
+        "mode": {
+          "enum": [
+            "uniform",
+            "free"
+          ]
+        },
+        "angles": {
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 36,
+          "items": {
+            "type": "number"
+          }
+        }
+      },
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "type": {
+              "enum": [
+                "thirds",
+                "golden-section"
+              ]
+            }
+          },
+          "required": [
+            "axes"
+          ],
+          "not": {
+            "anyOf": [
+              {
+                "required": [
+                  "x"
+                ]
+              },
+              {
+                "required": [
+                  "y"
+                ]
+              },
+              {
+                "required": [
+                  "rotation"
+                ]
+              },
+              {
+                "required": [
+                  "scale"
+                ]
+              },
+              {
+                "required": [
+                  "mirrored"
+                ]
+              },
+              {
+                "required": [
+                  "width"
+                ]
+              },
+              {
+                "required": [
+                  "height"
+                ]
+              },
+              {
+                "required": [
+                  "rayCount"
+                ]
+              },
+              {
+                "required": [
+                  "spread"
+                ]
+              },
+              {
+                "required": [
+                  "mode"
+                ]
+              },
+              {
+                "required": [
+                  "angles"
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "type": "object",
+          "properties": {
+            "type": {
+              "enum": [
+                "symmetry"
+              ]
+            }
+          },
+          "required": [
+            "x",
+            "y",
+            "rotation"
+          ],
+          "not": {
+            "anyOf": [
+              {
+                "required": [
+                  "axes"
+                ]
+              },
+              {
+                "required": [
+                  "scale"
+                ]
+              },
+              {
+                "required": [
+                  "mirrored"
+                ]
+              },
+              {
+                "required": [
+                  "width"
+                ]
+              },
+              {
+                "required": [
+                  "height"
+                ]
+              },
+              {
+                "required": [
+                  "rayCount"
+                ]
+              },
+              {
+                "required": [
+                  "spread"
+                ]
+              },
+              {
+                "required": [
+                  "mode"
+                ]
+              },
+              {
+                "required": [
+                  "angles"
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "type": "object",
+          "properties": {
+            "type": {
+              "enum": [
+                "golden-spiral"
+              ]
+            }
+          },
+          "required": [
+            "x",
+            "y",
+            "rotation",
+            "scale",
+            "mirrored"
+          ],
+          "not": {
+            "anyOf": [
+              {
+                "required": [
+                  "axes"
+                ]
+              },
+              {
+                "required": [
+                  "width"
+                ]
+              },
+              {
+                "required": [
+                  "height"
+                ]
+              },
+              {
+                "required": [
+                  "rayCount"
+                ]
+              },
+              {
+                "required": [
+                  "spread"
+                ]
+              },
+              {
+                "required": [
+                  "mode"
+                ]
+              },
+              {
+                "required": [
+                  "angles"
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "type": "object",
+          "properties": {
+            "type": {
+              "enum": [
+                "triangle"
+              ]
+            }
+          },
+          "required": [
+            "x",
+            "y",
+            "rotation",
+            "width",
+            "height"
+          ],
+          "not": {
+            "anyOf": [
+              {
+                "required": [
+                  "axes"
+                ]
+              },
+              {
+                "required": [
+                  "scale"
+                ]
+              },
+              {
+                "required": [
+                  "mirrored"
+                ]
+              },
+              {
+                "required": [
+                  "rayCount"
+                ]
+              },
+              {
+                "required": [
+                  "spread"
+                ]
+              },
+              {
+                "required": [
+                  "mode"
+                ]
+              },
+              {
+                "required": [
+                  "angles"
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "type": "object",
+          "properties": {
+            "type": {
+              "enum": [
+                "radial"
+              ]
+            },
+            "mode": {
+              "enum": [
+                "uniform"
+              ]
+            }
+          },
+          "required": [
+            "x",
+            "y",
+            "rotation",
+            "rayCount",
+            "spread"
+          ],
+          "not": {
+            "anyOf": [
+              {
+                "required": [
+                  "axes"
+                ]
+              },
+              {
+                "required": [
+                  "scale"
+                ]
+              },
+              {
+                "required": [
+                  "mirrored"
+                ]
+              },
+              {
+                "required": [
+                  "width"
+                ]
+              },
+              {
+                "required": [
+                  "height"
+                ]
+              },
+              {
+                "required": [
+                  "angles"
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "type": "object",
+          "properties": {
+            "type": {
+              "enum": [
+                "radial"
+              ]
+            },
+            "mode": {
+              "enum": [
+                "free"
+              ]
+            }
+          },
+          "required": [
+            "x",
+            "y",
+            "mode",
+            "angles"
+          ],
+          "not": {
+            "anyOf": [
+              {
+                "required": [
+                  "axes"
+                ]
+              },
+              {
+                "required": [
+                  "rotation"
+                ]
+              },
+              {
+                "required": [
+                  "scale"
+                ]
+              },
+              {
+                "required": [
+                  "mirrored"
+                ]
+              },
+              {
+                "required": [
+                  "width"
+                ]
+              },
+              {
+                "required": [
+                  "height"
+                ]
+              },
+              {
+                "required": [
+                  "rayCount"
+                ]
+              },
+              {
+                "required": [
+                  "spread"
+                ]
+              }
+            ]
+          }
+        }
+      ]
+    },
     "state": {
       "type": "object", "additionalProperties": false,
       "required": ["id", "number", "layout"],
@@ -158,6 +619,7 @@
           "type": "object", "additionalProperties": false,
           "required": ["frame", "layerOrder", "focusPoints", "directionLine", "areas", "images"],
           "properties": {
+        "plans": { "type": "array", "items": { "$ref": "#/$defs/compositionPlan" } },
             "frame": { "allOf": [{ "$ref": "#/properties/frame" }, { "type": "object", "required": ["bounds"] }] },
             "layerOrder": { "$ref": "#/properties/layerOrder" },
             "focusPoints": { "type": "array", "maxItems": 3, "items": { "$ref": "#/$defs/layoutPoint" } },
@@ -182,12 +644,23 @@
         "rotation": { "type": "number" }
       }
     },
+    "textCorners": {
+      "type": "array", "minItems": 4, "maxItems": 4,
+      "items": {
+        "type": "object", "additionalProperties": false, "required": ["x", "y"],
+        "properties": {
+          "x": { "type": "number", "minimum": 0, "maximum": 1 },
+          "y": { "type": "number", "minimum": 0, "maximum": 1 }
+        }
+      }
+    },
     "layoutArea": {
       "type": "object", "additionalProperties": false, "required": ["id", "x", "y", "area", "aspect"],
       "properties": {
         "id": { "type": "string", "pattern": "^area-[0-9]+$" },
         "x": { "type": "number" }, "y": { "type": "number" },
         "area": { "type": "number", "exclusiveMinimum": 0 },
+        "corners": { "$ref": "#/$defs/textCorners" },
         "aspect": { "enum": ["square", "free", "landscape", "portrait"] },
         "rotation": { "type": "number" },
         "width": { "type": "number", "exclusiveMinimum": 0 },

package/schemas/spatial-draft.schema.json

@@ -291,6 +291,9 @@
             "type": "number",
             "minimum": 0.7,
             "maximum": 1.4
+          },
+          "note": {
+            "type": "string"
           }
         }
       }
@@ -361,6 +364,9 @@
           "color": {
             "type": "string",
             "pattern": "^#[0-9a-fA-F]{6}$"
+          },
+          "note": {
+            "type": "string"
           }
         }
       }
@@ -451,6 +457,9 @@
                 "type": "null"
               }
             ]
+          },
+          "note": {
+            "type": "string"
           }
         }
       }
@@ -509,6 +518,9 @@
             "type": "integer",
             "minimum": 128,
             "maximum": 1024
+          },
+          "note": {
+            "type": "string"
           }
         }
       }

package/schemas/spatial-operations.schema.json

@@ -371,6 +371,9 @@
                 "type": "number",
                 "minimum": 0.7,
                 "maximum": 1.4
+              },
+              "note": {
+                "type": "string"
               }
             }
           }
@@ -621,6 +624,9 @@
               "color": {
                 "type": "string",
                 "pattern": "^#[0-9a-fA-F]{6}$"
+              },
+              "note": {
+                "type": "string"
               }
             }
           }
@@ -719,6 +725,9 @@
                     "type": "null"
                   }
                 ]
+              },
+              "note": {
+                "type": "string"
               }
             }
           }
@@ -1047,6 +1056,9 @@
                 "type": "integer",
                 "minimum": 128,
                 "maximum": 1024
+              },
+              "note": {
+                "type": "string"
               }
             }
           }

package/skills/human2ai/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: human2ai
-description: Collaborate through local Human2AI design sessions, its style library, and its CLI. Use in a consumer project containing .human2ai/integration.json to inspect, edit, refine, review, or undo design work; to draw a reference picture as editable scene or editorial composition (“把这张图的构图画到画布上”); to project existing UI into a layout canvas (“把 UI 放到画布上让我修改”); or to reuse a visual style. The consumer project's Agent owns downstream implementation.
+description: Collaborate through local Human2AI design sessions, its style library, and its CLI. Use in a consumer project containing .human2ai/integration.json to inspect, edit, refine, review, or undo design work; to draw a reference picture as editable scene or editorial composition (“把这张图的构图画到画布上”); to project existing UI into a layout canvas (“把 UI 放到画布上让我修改”); to model in the consumer project using a style and 3D spatial guidance; or to reuse a visual style. The consumer project's Agent owns downstream implementation.
+metadata:
+  version: "0.1.4"
 ---
 
 # Human2AI
@@ -30,26 +32,28 @@ If the integration config is missing, stop and tell the user that this repositor
 
 ## Use the shared style library
 
-The style library is global to the local Human2AI service. Each composition or UI session can bind one of its styles; the browser and Agent share that binding. Search it when the user asks to reuse a style or when you need to select a style for canvas processing:
+The style library is global to the local Human2AI service. Each composition, UI or spatial session can bind one of its styles; the browser and Agent share that binding. Search it when the user asks to reuse a style or when you need to select a style for canvas processing or consumer-project modeling:
 
 ```text
-<runner> style list [--category <visual|ui>] [--creator <user|agent>]
+<runner> style list [--category <visual|ui|spatial>] [--creator <user|agent>]
 <runner> style get --style <style-id>
 ```
 
-`style get` returns reference image URLs and the full description. Treat that description as an actionable design specification: layout, proportions, hierarchy, spacing, typography, palette, materials, and decorative treatment as applicable. Inspect available reference images to resolve the visual characteristics. The user's explicit content, functions, and placement requirements take precedence over the style specification.
+`style get` returns reference image URLs, an optional `previewModel.url`, and the full description. Treat that description as an actionable design specification: layout, proportions, hierarchy, spacing, typography, palette, materials, and decorative treatment as applicable. Inspect available reference images to resolve the visual characteristics. The user's explicit content, functions, and placement requirements take precedence over the style specification.
 
 When a style encountered during Agent work is worth keeping, save it directly as an Agent-created entry; there is no proposal or pending-review state:
 
 ```text
-<runner> style create --name <name> --category <visual|ui> --description <specification> --summary <sentence>
+<runner> style create --name <name> --category <visual|ui|spatial> --description <specification> --summary <sentence>
 <runner> style add-reference --style <style-id> --input <image> --expected-revision <n>
 ```
 
+For a program-generated 3D model example, follow the model-preview instructions in [spatial modeling](references/spatial-modeling.md#save-a-generated-style-example).
+
 A style may have no reference image, but its design specification must be non-empty. Supply a separate concise sentence capturing its distinctive visual traits (typically 30–60 Chinese characters, maximum 240 characters). Browser prompt copying adds only this sentence, without a model call or the full specification. Keep the sentence consistent when editing the specification. Older entries without a sentence fall back to their first description sentence until edited. The creation entrypoint permanently marks these entries as `agent`; entries created in the browser remain `user` even after Agent edits. Update or permanently delete only when the user requests it or it is otherwise clearly part of the current task:
 
 ```text
-<runner> style update --style <style-id> --expected-revision <n> [--name <name>] [--category <visual|ui>] [--description <specification>] [--summary <sentence>]
+<runner> style update --style <style-id> --expected-revision <n> [--name <name>] [--category <visual|ui|spatial>] [--description <specification>] [--summary <sentence>]
 <runner> style remove-reference --style <style-id> --reference <reference-id> --expected-revision <n>
 <runner> style delete --style <style-id> --expected-revision <n>
 ```
@@ -106,12 +110,22 @@ For spatial sessions, read [references/spatial.md](references/spatial.md). Creat
 
 When generating an image from a spatial camera, follow that reference's **Camera references for image generation** guidance for interpreting pose intent, correcting anatomical inaccuracies, and excluding guide markings from the generated image.
 
-## Choose refinement or style processing
+## Model in the consumer project
+
+When the user asks for final 3D models or a scene in their project, read [references/spatial-modeling.md](references/spatial-modeling.md). Combine the full style specification and reference images with the Human2AI spatial session's layout, scale, pose and camera guidance. Build and review the result using the consumer project's existing tools. A style binding does not alter the guide scene or record completion of external modeling. Use the spatial authoring workflow above only when the guide scene itself needs edits.
+
+## Choose design, planning, refinement or style processing
 
-A request for 精修, mathematical proportion, symmetry, focal guidance, or rule-based composition calls for the independent refinement workflow in [references/composition.md](references/composition.md). Do not infer a style request from these terms or bind a library style. Refinement may preserve the source without changes when the Agent finds no justified improvement. Use style processing below only when style application is part of the user’s intent.
+For requests to design or redesign composition content from focuses or planning guides, follow [Design content from composition planning](references/composition.md#design-content-from-composition-planning). Apply the same interpretation and visual checks when styling, refining or generating from an existing planned composition. With complex guides, especially radial fans, spirals or interacting plans, explicitly map their relationships to visible content before choosing shapes. Check focal placement and directional structure separately; preserving guide data or placing subjects at focuses alone does not fulfill the composition.
+
+For requests to add, inspect or adjust composition planning guides, follow [Shared composition planning](references/composition.md#shared-composition-planning). Read and edit the draft's `plans` through the CLI and save through `capture.commands.save`. Use `composition inspect` and its `planningIntersections` to locate guide crossings and read coordinates for requested placement. Editing guides alone leaves content nodes unchanged.
+
+A request for 精修 or for applying mathematical proportions, symmetry or focal relationships to canvas elements calls for the independent refinement workflow in [references/composition.md](references/composition.md). Do not infer a style request from these terms or bind a library style. Refinement may preserve the source without changes when the Agent finds no justified improvement. Use style processing below only when style application is part of the user’s intent.
 
 ## Process a canvas with its style
 
+This workflow applies to composition and UI canvases. For modeling from a spatial session, use the consumer-project workflow above.
+
 For a request to recover the composition of a reference picture, first follow the reference-projection workflow in [references/composition.md](references/composition.md). Abstract the structure that organizes attention, weight, rhythm and space; judge the resulting experience rather than resemblance to object outlines. Choose each shape for its contribution to the whole and explain that contribution in its description. New reference nodes have empty notes, and a new reference draft has an empty overall note. The supplied picture is the visual evidence for that task. Apply a different style only when requested; an existing binding must not silently redesign the recovered composition.
 
 When modifying a styled session, use `style.current.description` and its reference images as design constraints. A request to apply or improve the style calls for actual canvas edits, not just adding a style name or rewriting notes.
@@ -142,7 +156,7 @@ Reconnect after binding to obtain the current specification and save command. Bi
 
 For SVG icons, decorations, or outlines requested as image-node content, read [references/svg-images.md](references/svg-images.md). Both session types use their existing image nodes for SVG; the user describes the result in language and the Agent authors the source.
 
-- For `image-composition`, read [references/composition.md](references/composition.md) before drawing a reference picture, canvas processing, refinement or generation-reference work. Interpret light markers as approximately as ordinary shape regions: retain their broad lighting contribution while freely adapting width, length, continuity, edges and strength. User instructions and node notes take precedence. Approximate overall correspondence is sufficient; do not infer fixed-width stripes, strong contrast or exact coverage from the canvas.
+- For `image-composition`, read [references/composition.md](references/composition.md) before designing from focuses or planning guides, editing composition planning, drawing a reference picture, canvas processing, refinement or generation-reference work. Interpret light markers as approximately as ordinary shape regions: retain their broad lighting contribution while freely adapting width, length, continuity, edges and strength. User instructions and node notes take precedence. Approximate overall correspondence is sufficient; do not infer fixed-width stripes, strong contrast or exact coverage from the canvas.
 - For `ui-layout`, read [references/ui-layout.md](references/ui-layout.md) before modifying the layout document or implementing UI from a capture. Group multi-node controls during projection, and execute its standardization workflow before changing consumer components from canvas geometry.
 - For a future session type, use only the capture kind and operations returned by `session connect`. If no reference or operation supports the requested action, report that boundary instead of inventing a command.