human2ai 0.1.3 → 0.1.4

package/locales/en/common.json

@@ -72,7 +72,7 @@
     },
     "searchPlaceholder": "Search styles",
     "deleteTitle": "Delete this style?",
-    "deleteDescription": "The style and all of its reference images will be permanently deleted.",
+    "deleteDescription": "The style and all of its reference images and models will be permanently deleted.",
     "empty": "No styles yet",
     "noMatches": "No matching styles",
     "loading": "Loading styles",
@@ -84,6 +84,13 @@
     "promptSummary": {
       "label": "Style summary",
       "placeholder": "Summarize the defining visual traits in one sentence."
+    },
+    "model": {
+      "label": "Model example",
+      "loading": "Loading model",
+      "failed": "Could not preview the model",
+      "reset": "Reset model view",
+      "controls": "Drag to rotate, scroll to zoom. When focused, use arrow keys to rotate, + / − to zoom, and Home to reset."
     }
   },
   "notes": {
@@ -256,8 +263,6 @@
       "quadrilateral": "Rectangle",
       "textRegion": "Text region"
     },
-    "showGuideGrid": "Show grid",
-    "hideGuideGrid": "Hide grid",
     "canvasZoom": "Current zoom",
     "zoomOut": "Zoom out",
     "zoomIn": "Zoom in",
@@ -302,7 +307,16 @@
       "left": "left",
       "lightSourceNumber": "Light source {{index}}",
       "lightSourceGuidance": "- Like ordinary shape regions, light markers describe approximate visual intent and spatial relationships. Pale yellow identifies lighting, not color temperature. A source is distinct from the area it illuminates: interpret its origin and contribution in the scene. Rectangles suggest band-shaped or extended illumination; circles suggest localized illumination. Retain the broad lighting placement, extension trend and contribution to subject and space, while freely adapting width, length, curvature, continuity, edges and strength to the scene. User instructions and node notes take precedence; otherwise the Agent chooses. Do not infer fixed width, straight constant-width strips, full-frame coverage, medium-strong contrast or thumbnail prominence from the reference. Consider sources individually while allowing their visible effects to split, overlap or blend. Review whether the overall lighting broadly echoes the composition rather than comparing edges, segments or widths; tighten a constraint only when the user explicitly requests it, and do not ignore the authored lighting intent entirely.",
-      "lightBandGuidance": "Light-band intent: broadly retain the extended or band-like illumination and its spatial role here. Its realization may narrow, widen, curve, break up or blend with the scene; a complete, straight, constant-width or conspicuous stripe is not required. User instructions and this node’s notes take precedence for width, length, edges and strength; otherwise the Agent interprets them freely. An approximate overall correspondence is sufficient."
+      "lightBandGuidance": "Light-band intent: broadly retain the extended or band-like illumination and its spatial role here. Its realization may narrow, widen, curve, break up or blend with the scene; a complete, straight, constant-width or conspicuous stripe is not required. User instructions and this node’s notes take precedence for width, length, edges and strength; otherwise the Agent interprets them freely. An approximate overall correspondence is sufficient.",
+      "planningGuidance": "Use the following plans as composition intent alongside the overall requirements and notes. Do not draw the guide lines, axes, spiral or triangle outline in the artwork. Positions are relative to the top-left of the image; angles run clockwise from the rightward horizontal.",
+      "planningGrid": "- {{type}}: {{axes}} divisions.",
+      "planningSymmetry": "- Symmetrical composition: axis through the image center ({{x}}%, {{y}}%), direction {{rotation}}°.",
+      "planningSpiral": "- Golden spiral: pole at ({{x}}%, {{y}}%), outer radius directed at {{rotation}}°, radius {{scale}}% of the shorter image side, {{winding}}.",
+      "planningClockwise": "expanding clockwise",
+      "planningCounterclockwise": "expanding counterclockwise",
+      "planningTriangle": "- Triangular composition: isosceles triangle with vertices at {{points}}.",
+      "planningRadial": "- Radial composition: convergence point ({{x}}%, {{y}}%), {{rayCount}} evenly spaced rays starting at {{rotation}}° and spanning {{spread}}° clockwise.",
+      "planningRadialFree": "- Free radial composition: convergence point ({{x}}%, {{y}}%), {{rayCount}} rays with independent directions: {{angles}} (clockwise from the rightward horizontal)."
     },
     "depth": {
       "label": "Depth",
@@ -352,6 +366,48 @@
     "textRegion": {
       "cornerLabel": "Text outline corner {{index}}",
       "cornerHelp": "Select a text region and hold Ctrl to drag its corners. Focus a corner and use the arrow keys for fine adjustments."
+    },
+    "planning": {
+      "title": "Composition planning",
+      "add": "Add plan",
+      "empty": "No composition plans",
+      "types": {
+        "thirds": "Rule of thirds",
+        "golden-section": "Golden section",
+        "symmetry": "Symmetrical composition",
+        "golden-spiral": "Golden spiral",
+        "triangle": "Triangular composition",
+        "radial": "Radial composition"
+      },
+      "visible": "Show plan",
+      "axes": "Grid directions",
+      "both": "Horizontal and vertical",
+      "horizontal": "Horizontal",
+      "vertical": "Vertical",
+      "x": "Horizontal (%)",
+      "y": "Vertical (%)",
+      "rotation": "Rotation (°)",
+      "scale": "Spiral size (%)",
+      "mirrored": "Mirror spiral",
+      "handle": "Plan control {{index}}",
+      "help": "Shift-click to select multiple plans and drag a selected guide to move them together. Thirds, golden-section and symmetry guides stay fixed. Select thirds and golden-section plans in the sidebar. Arrow keys nudge; Delete removes a plan.",
+      "width": "Base width (%)",
+      "height": "Triangle height (%)",
+      "triangleHelp": "Drag the apex to rotate and adjust height. Drag a base corner to resize; both sides stay symmetric.",
+      "symmetryHelp": "The center stays fixed. Drag the other dot to one of eight regular directions or four frame-corner directions. Corner directions follow the frame ratio; duplicate positions merge for a square. Arrow keys step between positions.",
+      "spiralHelp": "Click the center dot to switch clockwise/counterclockwise. Drag it to move the spiral; drag the outer dot to rotate and resize.",
+      "spiralDirection": "Switch spiral direction (clockwise/counterclockwise)",
+      "rayCount": "Ray count",
+      "spread": "Spread (°)",
+      "radialHelp": "Uniform mode uses a starting direction and spread. In Free mode, drag each ray’s dot to adjust its direction; drag the center to move the convergence point. Switching to Free preserves directions; switching back to Uniform redistributes the current rays around a full circle.",
+      "lock": "Lock composition planning",
+      "unlock": "Unlock composition planning",
+      "showAll": "Show composition guides",
+      "hideAll": "Hide composition guides",
+      "radialMode": "Radial mode",
+      "radialUniform": "Uniform",
+      "radialFree": "Free",
+      "rayHandle": "Ray {{index}} direction"
     }
   },
   "uiSketch": {

package/migrations/0010_style_preview_models.sql

@@ -0,0 +1,8 @@
+CREATE TABLE style_preview_models (
+  style_id TEXT PRIMARY KEY REFERENCES style_entries(id) ON DELETE CASCADE,
+  id TEXT NOT NULL UNIQUE,
+  relative_path TEXT NOT NULL,
+  original_filename TEXT NOT NULL,
+  byte_size INTEGER NOT NULL CHECK (byte_size > 0),
+  created_at TEXT NOT NULL
+) STRICT;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "human2ai",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Local visual collaboration workspace for people and AI agents, with a browser UI and CLI.",
   "license": "MIT",
   "author": "贾思斋",

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 } },
@@ -152,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"],
@@ -163,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" } },

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 放到画布上让我修改”); 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
@@ -37,7 +39,7 @@ The style library is global to the local Human2AI service. Each composition, UI
 <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:
 
@@ -46,6 +48,8 @@ When a style encountered during Agent work is worth keeping, save it directly as
 <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
@@ -110,9 +114,13 @@ When generating an image from a spatial camera, follow that reference's **Camera
 
 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 refinement or style processing
+## Choose design, planning, refinement or style processing
+
+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 精修, 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.
+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
 
@@ -148,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.