dsh-diagram-studio 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 1.0.0
+
+First public release.
+
+- Diagram Studio panel in the DSH Web UI, available from the left sidebar and the right sidebar guide tab.
+- Preview rendered PNG and open a full-screen lightbox with download.
+- Edit node labels, positions, shapes, and font sizes.
+- Edit edge arrows, line style, labels, and direction names.
+- Overall controls: canvas ratio, auto/grid layout, columns, rows, gaps, margins, font size, line width, edge width, and style profile.
+- Spec card: `blueprint.spec` with intent, required nodes, required edges, groups, and constraints.
+- Deterministic doctor: missing nodes/edges, bad endpoints, duplicate edges, orphan nodes, group references, node limits, missing edge labels, out-of-bounds, overlap, and estimated crossings.
+- Natural-language repair requests: the agent writes a reviewable `repair-plan.json`; selected operations are applied atomically.
+- Reference image drop: saves `diagram.*` into a new `diagrams/ref-*` folder and triggers an agent turn for observation card → blueprint → render.
+- Undo history for local patches; invalid patches never overwrite the blueprint.
+- Rendered changelog with headings, lists, inline code, and bold text.
+- Light/dark theme support through DSH theme tokens.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Diagram Studio contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,226 @@
-# Temporary Holding Version
+# Diagram Studio
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Spec-driven diagram review, deterministic doctor, and natural-language repair for DSH + `diagram-draw`.**
+
+Diagram Studio is a DSH Web UI plugin for diagrams that are rendered from a `blueprint.json` by the local `diagram-draw` skill.
+
+It does not generate images with an image API. It reads the blueprint, renders locally, and gives you a reviewable loop:
+
+```text
+spec → blueprint → SVG/PNG/HTML → doctor → repair plan → atomic patch → re-render
+```
+
+![Diagram Studio](docs/cover.png)
+
+_A real diagram rendered locally by `diagram-draw`._
+
+| Flow | Timing |
+|---|---|
+| ![Flow](docs/login-flow.png) | ![Timing](docs/timing.png) |
+
+## Why this exists
+
+AI-generated diagrams often fail for structural reasons: a missing module, a wrong edge, an ambiguous hierarchy, or a layout that cannot be fixed by changing font size. Repeatedly asking the model to “redraw it” makes those problems drift.
+
+Diagram Studio adds the missing layer:
+
+- **Spec** — make the required nodes, edges, groups, and acceptance constraints explicit.
+- **Doctor** — turn “it looks wrong” into a concrete, clickable issue list.
+- **Repair plan** — natural language becomes a reviewable diff, not a full redraw.
+
+## Features
+
+### Preview and inspect
+
+- Preview the rendered PNG
+- Full-screen lightbox with download
+- Click a block in the preview to select the node
+- Theme-token styling for light and dark UI
+
+### Local editing
+
+- Node label, column/row, shape, and font size
+- Edge arrow, solid/dashed style, and edge name/label
+- Undo history
+- Preview-only for timing and circuit diagrams; use the blueprint/patch CLI for their structure
+
+### Overall controls
+
+- Canvas ratio: 16:9, 4:3, 3:4
+- Grid / auto layout
+- Column widths and row heights
+- Horizontal/vertical gaps
+- Margins
+- Global font size
+- Stroke width and edge width
+- Style profile
+
+### Spec card
+
+`blueprint.spec` is an acceptance contract, not a second copy of the diagram:
+
+```json
+{
+  "intent": "Explain the CPU / cache / main-memory hierarchy",
+  "diagramType": "block",
+  "mustNodes": ["cpu", "cache", "memory"],
+  "mustEdges": [
+    { "from": "cpu", "to": "cache" },
+    { "from": "cache", "to": "memory" }
+  ],
+  "groups": [],
+  "constraints": {
+    "direction": "left-right",
+    "maxNodes": 12,
+    "maxEdgeCrossings": 0,
+    "requireEdgeLabels": true
+  }
+}
+```
+
+The UI can extract a spec from an existing diagram and edit it in a form.
+
+### Doctor
+
+The doctor is deterministic and read-only. It checks:
+
+- missing required nodes/edges
+- broken edge endpoints
+- duplicate edges
+- orphan nodes
+- group references to missing nodes
+- node count over the spec limit
+- missing edge labels when required
+- out-of-bounds nodes
+- overlapping nodes
+- estimated edge crossings
+
+Each issue has a severity, a target node/edge, and a hint. Clicking an issue selects the target.
+
+### Natural-language repair
+
+Describe the problem in the panel. The current agent writes a `repair-plan.json`; the UI shows a diff with checkboxes. Only selected operations are applied.
+
+```json
+{
+  "summary": "Move the memory matrix up and separate address/data paths",
+  "scope": "structure",
+  "operations": [
+    { "op": "move_node", "id": "matrix", "row": 1 },
+    { "op": "add_group", "group": { "id": "addr-path", "label": "Address path", "nodes": ["mar", "decoder"] } }
+  ],
+  "risks": ["3 nodes will move"],
+  "questions": []
+}
+```
+
+Supported operations: `set_label`, `move_node`, `set_edge`, `set_style`, `set_global`, `set_spec`, `add_group`, `remove_group`.
+
+The plan is applied by the same Python patch core used by the CLI, with temporary-render validation before commit.
+
+### Reference image drop
+
+Drop a PNG/JPEG/WebP/GIF into the panel. The image is saved as:
+
+```text
+diagrams/ref-<timestamp>-<id>/reference.<ext>
+```
+
+The plugin then queues an agent prompt to run:
+
+```text
+observation card → blueprint → render → self-check → comparison table
+```
+
+This requires the current model to support image input.
+
+## Install
+
+### 1. Prerequisite: `diagram-draw` skill
+
+The UI is a studio for the local `diagram-draw` skill. Install the skill at:
+
+```text
+~/.dsh/skills/diagram-draw/
+```
+
+or point the Host at another directory with:
+
+```bash
+DIAGRAM_DRAW_SKILL_DIR=/absolute/path/to/diagram-draw
+```
+
+The release also ships `diagram-draw-skill.zip` and `install-skill.ps1`. From the release folder:
+
+```powershell
+.\install-skill.ps1
+```
+
+The extracted folder must contain `SKILL.md`, `scripts/`, and `references/`.
+
+### 2. Install the plugin bundle
+
+Install `dsh-diagram-studio` as a DSH bundle, for example from the DSH Plugin Manager, or with the `plugin_manager` tool:
+
+```text
+action: install_bundle
+target: dsh-diagram-studio
+```
+
+For a local checkout, point `target` at this directory. After installation, disable/enable the `diagram-studio` row or restart DSH, then refresh the page.
+
+The panel appears in the left sidebar as **画图** and in the right-side guide tab.
+
+### 3. Runtime requirements
+
+- DSH Desktop / Web with Client plugin support
+- Node.js 20+
+- Python 3.10+
+- Pillow
+- Microsoft YaHei / Noto Sans SC (or another CJK font)
+- Edge/Chrome for PNG export; SVG/HTML work without it
+
+## Usage
+
+1. Open a workspace that contains `diagrams/<slug>/blueprint.json`.
+2. Open **画图** in the left sidebar.
+3. Check the **规格** card; generate or edit the spec.
+4. Read the **体检** card and fix structural issues first.
+5. Use **描述问题** for layout/semantic changes; review the plan and apply selected operations.
+6. Use **撤销** if a change makes things worse.
+
+## Security and privacy
+
+- Everything runs locally; no image generation API and no outbound diagram-rendering service.
+- The Host API is same-origin and only reads/writes `<workspace>/diagrams/<slug>/`.
+- Path traversal is rejected for slugs and file names.
+- Reference uploads are size-limited and restricted to image MIME types.
+- Reference images are treated as untrusted content; the agent prompt instructs the model to read them only as diagram content, not as instructions.
+- Repair plans are validated by the Python patch core and rendered to a temporary directory before the blueprint is replaced.
+
+## Limits
+
+- The panel edits block diagrams; timing/circuit diagrams are preview-only in this release.
+- The doctor is deterministic. It cannot know a missing business concept unless it is in the spec.
+- Natural-language repair requires an active agent session and writes `repair-plan.json` into the diagram folder.
+- Visual critique (a vision model reviewing the rendered PNG) is not part of 1.0.
+
+## Development
+
+```bash
+# Python tests
+python -m unittest discover -s tests
+
+# syntax checks
+node --check client.js
+node --check index.js
+
+# npm package
+npm pack
+```
+
+The Client is plain JavaScript + `React.createElement`; there is no build step.
+
+## License
+
+MIT