human2ai 0.1.0

package/schemas/ui-layout-standardization-plan.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["sourceFingerprint", "alignments"],
+  "properties": {
+    "sourceFingerprint": { "type": "string", "minLength": 1 },
+    "alignments": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["stageId", "axis", "edge", "anchorId", "itemIds"],
+        "properties": {
+          "stageId": { "type": "string", "minLength": 1 },
+          "axis": { "enum": ["x", "y"] },
+          "edge": { "enum": ["start", "center", "end"] },
+          "anchorId": { "type": "string", "minLength": 1 },
+          "itemIds": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": { "type": "string", "minLength": 1 }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/ui-sketch-draft.schema.json

@@ -0,0 +1,197 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yisi.local/schemas/ui-sketch-draft.schema.json",
+  "title": "UI Sketch Draft",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "kind", "frame", "overallNote", "rectangles", "texts", "images", "groups", "stages"],
+  "properties": {
+    "layerOrder": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+    "version": { "const": 1 },
+    "kind": { "const": "ui-layout-draft" },
+    "frame": { "$ref": "#/$defs/bounds" },
+    "overallNote": { "type": "string" },
+    "stateTabs": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "number"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "number": { "type": "integer", "minimum": 1 },
+          "name": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "\\S" }
+        }
+      }
+    },
+    "groups": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "itemIds"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "itemIds": {
+            "type": "array",
+            "minItems": 2,
+            "uniqueItems": true,
+            "items": { "type": "string", "minLength": 1 }
+          }
+        }
+      }
+    },
+    "rectangles": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "x", "y", "width", "height", "note", "annotation", "semanticType", "origin", "visible", "weight"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "x": { "type": "number" },
+          "y": { "type": "number" },
+          "width": { "type": "number", "exclusiveMinimum": 0 },
+          "height": { "type": "number", "exclusiveMinimum": 0 },
+          "note": { "type": "string" },
+          "annotation": { "type": "string" },
+          "semanticType": { "type": "string" },
+          "origin": { "enum": ["user", "agent", "import"] },
+          "visible": { "type": "boolean" },
+          "weight": {
+            "enum": ["auto", "high", "medium", "low", "decorative"]
+          }
+        }
+      }
+    },
+    "texts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "x", "y", "text", "fontSize", "note", "annotation", "semanticType", "origin", "visible", "weight"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "x": { "type": "number" },
+          "y": { "type": "number" },
+          "text": { "type": "string" },
+          "fontSize": { "type": "number", "exclusiveMinimum": 0 },
+          "note": { "type": "string" },
+          "annotation": { "type": "string" },
+          "semanticType": { "type": "string" },
+          "origin": { "enum": ["user", "agent", "import"] },
+          "visible": { "type": "boolean" },
+          "weight": {
+            "enum": ["auto", "high", "medium", "low", "decorative"]
+          }
+        }
+      }
+    },
+    "images": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "x", "y", "width", "height", "assetId", "crop", "note", "annotation", "semanticType", "origin", "visible", "weight"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "x": { "type": "number" },
+          "y": { "type": "number" },
+          "width": { "type": "number", "exclusiveMinimum": 0 },
+          "height": { "type": "number", "exclusiveMinimum": 0 },
+          "assetId": {
+            "type": ["string", "null"],
+            "minLength": 1
+          },
+          "crop": {
+            "oneOf": [
+              { "type": "null" },
+              { "$ref": "#/$defs/imageCrop" }
+            ]
+          },
+          "note": { "type": "string" },
+          "annotation": { "type": "string" },
+          "semanticType": { "type": "string" },
+          "origin": { "enum": ["user", "agent", "import"] },
+          "visible": { "type": "boolean" },
+          "weight": {
+            "enum": ["auto", "high", "medium", "low", "decorative"]
+          }
+        }
+      }
+    },
+    "stages": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "rectangles", "texts", "images"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1, "not": { "const": "start" } },
+          "rectangles": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/stageRectangle" }
+          },
+          "texts": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/stageText" }
+          },
+          "images": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/stageRectangle" }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "imageCrop": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["x", "y", "width", "height"],
+      "properties": {
+        "x": { "type": "number", "minimum": 0, "maximum": 1 },
+        "y": { "type": "number", "minimum": 0, "maximum": 1 },
+        "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 },
+        "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 }
+      }
+    },
+    "bounds": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["x", "y", "width", "height"],
+      "properties": {
+        "x": { "type": "number" },
+        "y": { "type": "number" },
+        "width": { "type": "number", "exclusiveMinimum": 0 },
+        "height": { "type": "number", "exclusiveMinimum": 0 }
+      }
+    },
+    "stageRectangle": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "x", "y", "width", "height", "visible"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "x": { "type": "number" },
+        "y": { "type": "number" },
+        "width": { "type": "number", "exclusiveMinimum": 0 },
+        "height": { "type": "number", "exclusiveMinimum": 0 },
+        "visible": { "type": "boolean" }
+      }
+    },
+    "stageText": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "x", "y", "fontSize", "visible"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "x": { "type": "number" },
+        "y": { "type": "number" },
+        "fontSize": { "type": "number", "exclusiveMinimum": 0 },
+        "visible": { "type": "boolean" }
+      }
+    }
+  }
+}

package/skills/human2ai/SKILL.md

@@ -0,0 +1,149 @@
+---
+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.
+---
+
+# Human2AI
+
+Use Human2AI as the shared design-intent workspace. The user primarily edits and reviews in the browser. Use the CLI against the same typed session, then perform any downstream implementation in the consumer project yourself.
+
+## Choose the operation channel
+
+Default to the CLI for service checks, session discovery, capture reads and edits, state changes, refinement, asset access, and preview export. An open Human2AI page is not a prerequisite. Read structured captures to inspect document contents; do not scrape the page or simulate clicks and drags for operations the CLI supports.
+
+Use Chrome MCP only when the task actually requires browser interaction, such as reproducing an interaction bug or exercising a consumer interface state that CLI data and exported artifacts cannot verify. Explain the interaction being checked before invoking it. Connecting to Human2AI, saving a canvas, or visually inspecting a static result alone does not require Chrome MCP. Export previews with the session's CLI operations and view the local image; rasterize SVG locally when the image viewer needs a bitmap. If that visual inspection is unavailable, report the limitation instead of automatically switching to Chrome MCP.
+
+## Resolve the local integration
+
+Read `.human2ai/integration.json` from the consumer repository before invoking the CLI. Execute its `runner` as an argument array and append the Human2AI arguments shown below. Do not assume that `human2ai` is globally installed, install a registry package, or access the Human2AI SQLite database directly.
+
+Run the integration checks from the consumer repository root:
+
+```text
+<runner> integration doctor --root <consumer-root>
+<runner> service status
+```
+
+When `integration doctor` returns `update-available`, run `<runner> integration sync --root <consumer-root>` immediately and continue. A copied Skill is replaced only when its installed digest still matches the managed version. If synchronization reports `INTEGRATION_CONFLICT`, do not overwrite the consumer copy; report the changed path. A linked Skill already reflects source edits, while `sync` only refreshes its recorded digest.
+
+If the integration config is missing, stop and tell the user that this repository has not been connected to its local Human2AI source. Do not guess the source path.
+
+## 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:
+
+```text
+<runner> style list [--category <visual|ui>] [--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.
+
+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 add-reference --style <style-id> --input <image> --expected-revision <n>
+```
+
+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 remove-reference --style <style-id> --reference <reference-id> --expected-revision <n>
+<runner> style delete --style <style-id> --expected-revision <n>
+```
+
+On a revision conflict, read the current entry again and reconcile before retrying. Never attempt to change `creatorType`.
+
+## Create or connect to the shared session
+
+Check the service before starting work. If `service status` returns `SERVICE_UNAVAILABLE`, execute the config's `service.start` as an argument array in a persistent terminal, wait for it to become ready, and retry the status command. Do not append `web` to the CLI runner when `service.start` provides a different local development command.
+
+Use the session identifier supplied by the user or browser when one exists. When the requested work needs a new Human2AI workspace, inspect current projects and sessions before creating only the needed session:
+
+```text
+<runner> project list
+<runner> session list [--project <project-id>]
+<runner> session create --type <image-composition|ui-layout|spatial> --title <title> [--project <project-id>]
+```
+
+Reuse a clearly matching project when available. Otherwise create an unassigned session instead of inventing project organization. After creation, use the returned session identifier for both the Agent CLI and browser page.
+
+Connect using the resolved session identifier:
+
+```text
+<runner> session connect --session <session-id>
+```
+
+Treat the returned `session-connection` JSON as the discovery contract. Read `session.sessionType`, `ui.editUrl`, `capture.kind`, `capture.latest`, `capture.commands`, `images.commands`, `style.current`, `style.commands`, and `operations`. The command fields are argument arrays to append to the configured `runner`; do not hardcode API paths or operations that the connection does not expose.
+
+Use `<runner> session open --session <session-id>` when the user wants the review page opened. If the environment cannot open a browser, provide `ui.editUrl` instead.
+
+## Modify captures immediately
+
+Read the latest saved capture, preserve its schema, apply the requested change, and save it immediately with optimistic concurrency:
+
+```text
+<runner> capture list --session <session-id>
+<runner> capture get --session <session-id> --kind <capture-kind> --revision <n>
+<runner> capture save --session <session-id> --kind <capture-kind> --input <document.json> --expected-revision <n>
+```
+
+Do not create proposal, approval, or staging states. A successful save appends an immutable revision and an open clean browser page displays it. If the service reports `DRAFT_REVISION_CONFLICT`, reconnect, read the new latest capture, reconcile the user's request with it, and save against that revision rather than overwriting it.
+
+Undo the latest Agent change when requested:
+
+```text
+<runner> capture undo --session <session-id> --kind <capture-kind> --change-revision <n> --expected-revision <n>
+```
+
+Undo appends the previous document as a new revision; it never deletes history.
+
+## Author a 3D space
+
+For spatial sessions, read [references/spatial.md](references/spatial.md). Create and pose articulated characters, extend custom morphologies, place simple geometry, and edit named output cameras through `spatial apply`. World position and world rotation locks are independent hard constraints. Render and inspect the requested camera after every completed Agent task. Composition nodes can reference those cameras and follow saved scene changes, or keep the current PNG as an independent image node.
+
+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
+
+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.
+
+## Process a canvas with its style
+
+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.
+
+If the user names a style, bind it. Otherwise retain an existing binding; when processing calls for a style and none is bound, choose a suitable library entry yourself based on the canvas and the user's goal. `visual` and `ui` are useful search filters, not restrictions on binding. Read candidate specifications before selecting and briefly explain the choice. Use the returned binding commands:
+
+```text
+<runner> session style --session <session-id>
+<runner> session bind-style --session <session-id> --style <style-id> --expected-revision <session-revision>
+<runner> session unbind-style --session <session-id> --expected-revision <session-revision>
+```
+
+Reconnect after binding to obtain the current specification and save command. Binding alone does not alter the canvas. Deleting a library style clears its bindings while retaining canvas history.
+
+1. Read the latest capture and the full current specification. If `capture.latest.styleProcessing` exists, read its `resultRevision` as the prior processing baseline and compare it with the latest capture. Preserve subsequent user changes; in particular, do not recreate accents the user removed without a new request.
+2. Preserve existing ids, origins, user notes, visible text, content/function and approximate spatial arrangement. Adjust proportions, size, whitespace, alignment, hierarchy and moderate placement/rotation where the specification supports it. Add purposeful decorative elements when helpful. Existing explicit placement requirements win over stylistic preferences.
+3. Set new nodes to `origin: "agent"`. Use `annotation` for a short design-role description; for a newly added decoration, its initial `note` should describe the intended visible content so it survives prompt export. Existing notes remain user instructions. Use the session-specific reference below for its coordinate system, allowed geometry and stages.
+4. Save the full editable draft using `style.commands.save`, which includes the canvas, style and session revisions:
+
+   ```text
+   <runner> capture save --session <session-id> --kind <capture-kind> --input <document.json> --expected-revision <canvas-revision> --style <style-id> --style-revision <style-revision> --session-revision <session-revision>
+   ```
+
+   `STYLE_PROCESSING_STALE` or `DRAFT_REVISION_CONFLICT` means the source changed. Reconnect, read the latest canvas and style, and reconcile before retrying. Never remove the style flags to bypass a conflict. Ordinary user edits inherit processing metadata; undo restores the previous document and its processing metadata.
+5. Export and inspect the saved revision through the session-specific CLI preview command, then summarize the concrete changes. The draft communicates editable structure and visual intent; carry the full specification into authorized downstream implementation or image generation for details the canvas does not render, such as materials and typography. The browser's copied prompt remains a compact handoff using the single style sentence.
+
+## Route by session type
+
+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 `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.
+
+Human2AI captures design structure and intent, including SVG image content when requested. After the user's review, decide and complete the appropriate code, asset, article, music, build, or test work in the consumer project under that project's instructions.

package/skills/human2ai/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Human2AI"
+  short_description: "Collaborate through local Human2AI design sessions"

package/skills/human2ai/references/composition-projection.md

@@ -0,0 +1,170 @@
+# Reference picture to editable composition
+
+## Read the picture and session
+
+Use the image attached by the user or the local image they identify. Actually inspect it with the environment's image-viewing capability; a filename or verbal description alone does not establish its contents. If it is unavailable, request the missing image before drawing from it.
+
+Follow `SKILL.md` to resolve the integration and connect to a matching `image-composition` session. Read its latest capture when one exists. Use its selected `processingSemantic` unless the user explicitly requests a different mode. An explicit choice in the conversation counts as the user's selection and may be saved in the draft. If neither the session nor the user selects Scene (`scene-composition`) or Editorial (`editorial-layout`), ask once before drawing; do not infer the mode from the picture.
+
+For a new composition, match the picture's aspect ratio within the supported frame range below. For an existing session, preserve its frame and unrelated nodes unless the request calls for replacing them. If the destination or replacement scope is materially ambiguous, resolve that before overwriting existing intent. A bound style remains bound, but recovering a reference picture does not itself request restyling; use the ordinary Capture save command. When the user also requests a style adaptation, use the style-processing workflow and its save command.
+
+## Recover the structure that shapes the viewing experience
+
+Draw an abstraction of how the picture organizes attention, weight, movement and space. Success is retaining the structure and its perceptual effect when the pictured objects and surface treatment change. Recognizable silhouettes, matching bounding boxes and accurate pixel gaps are not the default acceptance criteria. The reference supplies evidence for the composition; it is not a contour template. Honor an explicit request for precise reproduction separately, without making it the default for composition work.
+
+### Understand the whole before selecting shapes
+
+Inspect the picture at thumbnail scale, then full size only to resolve uncertain relationships. Form a concise working reading of what makes it feel organized: where attention concentrates, what balances that concentration, how the eye can move, and where density gives way to breathing room. Ground terms such as calm, tension, weight or spaciousness in visible relationships. Do not attribute feelings produced mainly by subject matter, materials or lighting to geometry alone, or claim to know the designer's intent or every viewer's reading order.
+
+For example, a dense lower-left text mass opposed by a broad lower-right image mass can give a banner an asymmetric balance; a more compact mass higher up can lift attention away from the bottom edge, while a quieter center gives the active regions room. This reading determines the drawing. Starting with “glass here, record player there” and later adding the word “balance” does not.
+
+Keep this whole-picture reading in the Agent's reasoning or concise handoff, not in `overallNote`. It is a hypothesis to verify against the drawn result, not an invented theme to impose on every reference.
+
+### Choose geometry by contribution, not resemblance
+
+Use areas to express concentrations of visual weight, supporting fields and coherent reading units. Their size, elongation, direction, spacing and overlap should make the identified effects legible. A region can stand for several objects, part of a larger image, or a broad tonal mass. Choose a primitive for that role; it need not follow the object's outline. Preserve relative hierarchy, approximate placement and the reference's essential relationships. Positions and envelopes may be simplified or moderately adjusted to express them in the selected frame, subject to explicit user constraints and subsequent user edits.
+
+Use two contribution checks:
+
+- **Too coarse:** merging masses or leaving a subject free to drift inside a large image box would erase a counterweight, collapse a reading step, crowd a text area, or change a meaningful sense of depth, openness or movement. Give that role enough actual geometry to remain effective; naming it in a description is insufficient.
+- **Too detailed:** removing a shape changes only object recognition, local contour accuracy, texture or a minor typographic distinction. Absorb or omit it. Separate a small accent only when it makes a distinct contribution at the scale of the whole, or the user explicitly needs it editable.
+
+There is no node quota and no rule that every object, image or group needs one node. Similar elements can share a mass when they act together; retain their separation when it creates rhythm, openness or depth. Do not collect distant objects merely because they share an identity. A visual unit may use a few shapes, but every extra span must preserve a perceptual effect beyond making the object look more recognizable. An identifiable horn, curved edge or opening does not automatically deserve reconstruction. If a simpler mass or directional cue conveys the same effect, use it. Do not build a duplicate enclosing shape over those spans.
+
+A background area earns its place by an effect such as unifying dispersed accents or establishing figure-ground contrast, not simply because the source is a photograph. A photograph's outer footprint cannot replace internal masses that balance text or organize attention. Conversely, do not automatically draw the photo rectangle when the frame and main masses already carry its role. A fixed image used only as a layout slot may remain one footprint when its interior is outside the requested composition work.
+
+A focus point locates concentrated attention; an area expresses its spread and weight. A direction line can express a dominant flow, but it spans the canvas and cannot act as a short connector, curve or divider. Use none of these marks automatically. Negative space is expressed through neighboring masses and gaps, not through invented exclusion boxes. The draft has no group container, exclusion enforcement or mandatory layers.
+
+Use `shotScale` and `visualWeight` to support the reading, while making the geometry carry what it can. Metadata alone does not render tonal contrast or make a large rectangle visually quiet. Array order controls painting. Keep `images: []` for an abstract projection; placing the reference screenshot on the canvas does not perform this abstraction.
+
+### Apply the reading to the selected mode
+
+| Mode | Organize | Judge the effect through |
+| --- | --- | --- |
+| Scene | Main and supporting masses, depth, scale contrasts, framing and motion | Dominance versus counterbalance, near/far separation, enclosure versus openness, stability versus directional tension |
+| Editorial | Information hierarchy, text/image weight, grouping, density and gaps | Likely attention priorities and reading transitions, asymmetric or symmetric balance, breathing room and pace |
+
+For a scene with a giant subject and nearby people, size contrast and foreground overlap may create monumentality and depth. Retain those relationships without reconstructing the subject's anatomy. Keep a silhouette opening only when it contributes to that spatial reading or tension, not merely to identifying the animal. An isolated foreground accent may need its own mass to give the scene a counterweight or nearer scale reference.
+
+For a layout with a glass and a record player, represent their compact upper mass and broad lower mass when those weights organize the surrounding typography. The cup rim and disc outline need not be recognizable. A brand lockup, issue badge or compact call to action normally remains one reading unit with its immediate backing; differences in internal font size alone do not create separate compositional roles. Split text only to retain a distinct reading step, meaningful offset or directional effect. Preserve readable source wording in `displayText`, even when its spatial representation is abstracted.
+
+Retain a curved arrangement's lightness, turning movement or enclosing effect with the simplest useful gesture; do not trace its bends as a sequence of construction pieces. Use a few spans only if the effect otherwise disappears. Do not impose a ban on image/text overlap: deliberate overlap can bind them into one visual field. Preserve legibility and breathing room where they matter, rather than reproducing every measured gap. A round badge can use one text-region envelope when its compact counterweight matters more than its exact circular edge.
+
+### Keep descriptions, user notes, and lettering separate
+
+Preserve readable source lettering in text-region `displayText`, including punctuation and line breaks that matter. Never invent a transcription for unreadable text: leave it unspecified and explain the uncertainty in the node description. An empty `displayText` remains a text region and means the wording is unspecified for later generation. The browser canvas displays abstract typography marks, not the exact font or lettering; the CLI `inspect --preview` SVG shows plain region shapes. The CLI preview currently leaves ellipses axis-aligned even when they have rotation; read the saved rotation and report this preview limitation when it affects visual verification. Read `displayText` from the saved draft to check its wording. Colors, materials, depth and weight metadata are not a complete rendered theme.
+
+Assign stable ids and `origin: "import"` to every node recovered from the reference, including focus and direction marks. Reserve `origin: "agent"` for new design additions the user requests and `user` for browser-created nodes. Editing a node preserves its origin.
+
+Write `annotation` in the user's language to explain **what this element's presence contributes to the composition**. Connect a visible characteristic to its relationship with another mass or space and the resulting perceptual effect. Usually one sentence is enough. A short source-object reference can help identification, but the subject of the explanation is its compositional role. These are explanations of the current structure, not instructions to change it.
+
+| Merely describing the picture | Explaining the contribution |
+| --- | --- |
+| “手与酒杯在标题上方，杯底保留间隙” | “上方紧凑的重块将注意力从底边抬起，与右下横向大形形成斜向呼应，让下方密集文字有呼吸空间。” |
+| “右下是低而宽的唱片机，与标题错开” | “右下宽而平缓的体量承接上方的动势，与左下高对比文字形成不对称的平衡，使画面重心稳定。” |
+| “分类文字分成三段，沿弧线排列” | “中间轻而疏的转向节奏连接两侧重块，给视线留出经过的空隙，减轻大面积图文的拥挤感。” |
+| “大主体前方是一排人群” | “低矮、重复的前景节奏提供尺度参照并遮住主形底部，使后方大形显得更高、更远。” |
+
+Avoid interchangeable praise such as “丰富层次”“提升美感”“增强平衡” without saying what changes and through which relationship. Do not claim an effect just because a node needs a description: if it has no distinct contribution, revisit its geometry, grouping or necessity. Hiding the descriptions should leave a legible composition; reading them should explain why it feels that way. Source-dependent contrast or other qualities the canvas cannot show should be identified as such, not claimed as visibly rendered.
+
+Every newly imported node must have `note: ""`, including focus and direction nodes. For a new reference composition, set `overallNote: ""` too. Do not put the image analysis, generation instructions, a copy of the description, or a composition summary into notes. These fields remain available for the user's instructions. Preserve existing user notes when continuing a draft. Node descriptions remain in the draft for subsequent Agent work; the browser's compact prompt does not export them, which is not a reason to copy them into notes.
+
+## Author a complete draft
+
+Use this format directly; no project-source import, extra API, or new capture kind is needed. Coordinates are signed world units referenced to **1200 × 800**, not output pixels. `frame.width` and `frame.height` are integer output dimensions from 256 to 4096, with width/height from 0.5 to 2. `frame.bounds` locates the crop in world units. Always include it to avoid legacy-coordinate migration. For an unsupported picture ratio, resolve the desired crop or framing with the user rather than distorting it.
+
+Choose the abstract masses in the selected frame first. The following converts their chosen positions to canvas coordinates; it does not require tracing source pixels. For a visual point `(u, v)` expressed as fractions of the output frame and frame bounds `b`:
+
+```text
+x = b.x + u * b.width
+y = b.y + v * b.height
+width = regionWidthShareOfOutputFrame * b.width
+height = regionHeightShareOfOutputFrame * b.height
+area = width * height * shapeFactor
+```
+
+When the user explicitly requests a particular crop, padding or precise registration to the source, incorporate that framing before conversion and keep the source scale consistent on both axes. Preserve the chosen output ratio in either case.
+
+`shapeFactor` is 1 for a quadrilateral, π/4 for a free ellipse (`primitive: "circle"`), and 1/2 for a triangle. `x/y` locate the center of a rectangle or ellipse; triangles use their centroid, two-thirds of the height below their apex. Positive rotation turns clockwise in the screen's downward y-axis. Keep `area` consistent with the unrotated dimensions. `frame.bounds.width * 1200 / (frame.bounds.height * 800)` must equal the output aspect ratio.
+
+Required top-level fields are `version: 1`, `kind: "composition-draft"`, `processingSemantic`, `frame`, `overallNote`, `focusPoints`, `directionLine`, `areas`, and `images`. Use empty arrays, `null` for an absent direction line, and an empty overall note for a new reference composition.
+
+All nodes carry `origin`, `note`, `annotation`, `semanticType` and `shotScale` (`auto`, `foreground`, `midground`, `background`). Use a concise descriptive semantic type; only `text-region` has special text behavior.
+
+- Areas: ids `area-<integer>`, `primitive` (`circle`, `triangle`, `quadrilateral`), `x`, `y`, `area`, `aspect`, `visualWeight`, and optional `rotation`. Prefer `aspect: "free"` with explicit positive `width` and `height` for picture footprints. Weights are `auto`, `high`, `medium`, `low`, or `decorative`. A `text-region` uses a free quadrilateral and must include `displayText`; other areas must omit `displayText`. Array order determines area painting order; `shotScale` does not reorder nodes automatically.
+- Focus points: ids `focus-<integer>` and `x/y`; at most three, added only where useful.
+- Direction line: id `direction-1`, `x/y`, and `rotation`; at most one.
+- Keep `images: []` for an abstract projection. Represent source imagery as areas. Existing image nodes in a reused draft must retain their asset references and crop unless changing them is requested.
+
+These small examples demonstrate the payload and role explanations, not templates to impose on other pictures. Their object names identify the source content; the geometry carries transferable relationships.
+
+### Scene example: background mass and foreground subject
+
+```json
+{
+  "version": 1,
+  "kind": "composition-draft",
+  "processingSemantic": "scene-composition",
+  "frame": { "width": 1200, "height": 800, "bounds": { "x": 0, "y": 0, "width": 1, "height": 1 } },
+  "overallNote": "",
+  "focusPoints": [
+    { "id": "focus-1", "x": 0.72, "y": 0.48, "origin": "import", "note": "", "annotation": "Concentrated attention in the upper part of the foreground mass interrupts the broad horizontal sweep", "semanticType": "subject-focus", "shotScale": "foreground" }
+  ],
+  "directionLine": null,
+  "areas": [
+    { "id": "area-1", "primitive": "quadrilateral", "x": 0.32, "y": 0.55, "area": 0.21, "aspect": "free", "width": 0.6, "height": 0.35, "rotation": 0, "visualWeight": "low", "origin": "import", "note": "", "annotation": "The broad, quiet horizontal field counterbalances the narrow upright mass and gives the scene lateral breathing room", "semanticType": "landscape", "shotScale": "background" },
+    { "id": "area-2", "primitive": "quadrilateral", "x": 0.72, "y": 0.65, "area": 0.081, "aspect": "free", "width": 0.18, "height": 0.45, "rotation": 0, "visualWeight": "high", "origin": "import", "note": "", "annotation": "The compact upright mass concentrates weight on the right, creating an asymmetric balance with the wide quiet field", "semanticType": "figure", "shotScale": "foreground" }
+  ],
+  "images": []
+}
+```
+
+### Editorial example: type over photography with two subject masses
+
+The photograph fills the background. Its key subjects need geometry because they organize the space around the type; another full-frame image rectangle would add no necessary boundary here.
+
+```json
+{
+  "version": 1,
+  "kind": "composition-draft",
+  "processingSemantic": "editorial-layout",
+  "frame": { "width": 1200, "height": 600, "bounds": { "x": 0, "y": 0, "width": 1, "height": 0.75 } },
+  "overallNote": "",
+  "focusPoints": [],
+  "directionLine": null,
+  "areas": [
+    { "id": "area-1", "primitive": "circle", "x": 0.36, "y": 0.27, "area": 0.07225663103256524, "aspect": "free", "width": 0.23, "height": 0.4, "rotation": 0, "visualWeight": "high", "origin": "import", "note": "", "annotation": "The upright upper mass lifts attention above the lower pair, keeping the composition from settling into a single bottom-heavy band", "semanticType": "vase-group", "shotScale": "auto" },
+    { "id": "area-2", "primitive": "circle", "x": 0.73, "y": 0.57, "area": 0.060475658581603514, "aspect": "free", "width": 0.35, "height": 0.22, "rotation": 0, "visualWeight": "medium", "origin": "import", "note": "", "annotation": "The low, broad mass opposes the dense heading across a gap, providing a stable counterweight without joining it into a solid strip", "semanticType": "bowl-group", "shotScale": "auto" },
+    { "id": "area-3", "primitive": "quadrilateral", "x": 0.23, "y": 0.585, "area": 0.054, "aspect": "free", "width": 0.36, "height": 0.15, "rotation": 0, "visualWeight": "high", "displayText": "ROOM TO\nBREATHE", "origin": "import", "note": "", "annotation": "Dense horizontal type establishes the primary reading anchor, held in balance by the broader image mass to its right", "semanticType": "text-region", "shotScale": "auto" },
+    { "id": "area-4", "primitive": "quadrilateral", "x": 0.86, "y": 0.1, "area": 0.0128, "aspect": "free", "width": 0.16, "height": 0.08, "rotation": 0, "visualWeight": "low", "displayText": "VOL. 04", "origin": "import", "note": "", "annotation": "The isolated small label punctuates the open upper-right field while remaining subordinate to the main reading anchor", "semanticType": "text-region", "shotScale": "auto" }
+  ],
+  "images": []
+}
+```
+
+## Save, inspect, and continue editing
+
+Before saving, check every region against the whole-picture reading: what effect does it contribute, through which relationship, and is that contribution expressed in the drawing? Remove geometry justified only by resemblance. Restore a missing weight, gap or direction when its absence changes the intended experience. Descriptions must explain the contribution rather than supply one after the fact. Verify that all new notes and the new overall note are empty.
+
+Save the complete JSON with `capture.commands.save` from the connection, using its latest revision (0 before the first save). Keep the returned revision as the projection baseline. Use `composition inspect --session <session-id> --revision <saved-revision> --preview <preview.svg>` and actually view the local result, rasterizing it locally when the image viewer needs a bitmap. Follow the parent Skill's operation-channel rule; static preview inspection does not require Chrome MCP. Compare it with the reference at a size where both whole frames are visible, without relying on node descriptions:
+
+- Is attention concentrated in comparable places, with the same dominant and subordinate roles?
+- Does the balance of mass and open space preserve the identified stability, tension, depth or breathing room? Does the rhythm remain dense, loose, steady or turning where it matters?
+- If the objects were replaced by different content with these same visual roles, would the structural effect still work? If only object recognition survives, reconsider the abstraction. This is a thought experiment, not a request to generate another image.
+- Has an incidental contour or extra colored region become falsely prominent? Would merging it change the experience or only make the object less recognizable?
+- Do the descriptions explain the observed relationships and effects? If an effect depends on contrast the canvas does not render, is that dependency clear instead of being mistaken for a successful visual check?
+
+If it reads as a parts diagram, regroup around compositional contributions; better wording alone does not repair the drawing. If simplification lost a necessary effect, restore only the geometry needed to convey it. Correct those discrepancies and save against the latest revision. Do not add pieces merely to improve silhouette likeness. Schema validation and a low node count alone do not verify visual quality. Report limitations that affect the retained structure or experience, and unavailable visual inspection; ordinary omission of photographic detail is expected. These authoring checks guide subsequent work, not runtime guarantees of a generated picture's layout.
+
+Open or provide the session's `ui.editUrl`; an already open clean page receives the saved draft. If the request ends at an editable canvas, hand it off there. The first saved revision has no predecessor and cannot be undone; later latest revisions can be undone through the normal Capture command.
+
+When the user asks to continue after editing, read the latest capture and, when needed, the retained projection baseline. Preserve stable ids, origins, notes, required text, and user-added nodes; do not regenerate the original picture's layout over their changes or restore nodes they removed without a request. Treat edits as revised composition intent. They do not modify the reference image itself. Carry node descriptions as context into any separately authorized downstream image work.
+
+## Basis for these drawing rules
+
+These are Human2AI authoring decisions adapted from the following principles, not a universal formula or a requirement to research every new picture:
+
+- [Getty: Principles of Design](https://www.getty.edu/education/teachers/building_lessons/principles_design.pdf) explains visual weight, emphasis, movement, rhythm and unity. Here, those relationships determine whether a region deserves to exist.
+- [James Gurney: First Impressions](https://gurneyjourney.blogspot.com/2011/04/first-impressions.html) discusses deliberately seeing broad masses through defocusing or squinting. Here, the thumbnail pass precedes choosing nodes.
+- [NN/g: Proximity](https://www.nngroup.com/articles/gestalt-proximity/) and [Similarity](https://www.nngroup.com/articles/gestalt-similarity/) describe perceptual grouping. Here, shared appearance and proximity support aggregation while major spatial separations remain visible.
+- [Art Prof: Great 2D Compositions](https://artprof.org/learn/fundamentals/composition/great-2d-compositions/) emphasizes varying shape sizes, attention, and balancing visually active and quiet areas. Here, simplification retains meaningful small accents and negative space.