From d52497440e97d4c53e84eeeb0b937f98580a0cd7 Mon Sep 17 00:00:00 2001
From: clawdbot <clawdbot@local>
Date: Thu, 29 Jan 2026 15:58:04 +0800
Subject: [PATCH] docs: add runnable editor demo + build/preview instructions

---
 README.md | 100 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..64378db
--- /dev/null
+++ b/README.md
@@ -0,0 +1,100 @@
+# AstralView — Runnable BI Dashboard Editor (goView-like)
+
+This repo contains a runnable **BI dashboard screen editor** (AstralView) built as a simple product you can run locally and build as static assets.
+
+## A) Runnable dev demo (local editor)
+
+### Prerequisites
+- Node.js (recommended: the version used in this workspace)
+- pnpm (repo pins `pnpm@9.15.4` via `packageManager`)
+
+### Install
+```bash
+pnpm install
+```
+
+### Run the editor (dev)
+```bash
+pnpm --filter @astralview/editor dev
+```
+
+Then open the URL printed by Vite (typically `http://localhost:5173`).
+
+### What you should see
+- A **default demo BI screen**.
+- Default screen size: **1920×1080**.
+- You can select widgets, multi-select, move/resize, reorder layers, and edit properties in the inspector.
+
+## B) Publishable build artifact (build output + how to preview/serve)
+
+### Build
+```bash
+pnpm --filter @astralview/editor build
+```
+
+Build output:
+- `packages/editor/dist/` (static assets)
+
+### Preview the production build locally
+```bash
+pnpm --filter @astralview/editor preview
+```
+
+### Serve in production
+Serve the `packages/editor/dist/` folder with any static file server (Nginx, Caddy, Vercel static, etc.).
+
+Example:
+```bash
+pnpm --filter @astralview/editor build
+npx serve packages/editor/dist
+```
+
+## Data format (import/export)
+
+- Export: editor exports the **AstralView Screen JSON** (includes `width`/`height`, nodes, etc.).
+- Import:
+  - AstralView Screen JSON is validated/sanitized via schema migration.
+  - goView-like exports are also supported via conversion.
+- Default canvas size is **1920×1080**, and import/export preserves screen `width`/`height`.
+
+## C) Acceptance checklist (goView-like UX) — status
+
+### Canvas defaults
+- [x] Default screen/canvas size is **1920×1080**.
+- [x] Import/export preserves `width`/`height` (AstralView Screen JSON).
+- [x] goView conversion uses 1920×1080 fallbacks when width/height are missing.
+
+### Core editor workflows
+- [x] Selection
+  - [x] Right-click selects item (goView-ish)
+  - [x] Right-click on empty space does **not** clear selection
+- [x] Multi-select transform
+  - [x] Move
+  - [x] Group bounding-box resize
+- [x] Layers panel
+  - [x] Reorder (drag)
+  - [x] Lock / hide
+- [x] Context menu
+  - [x] Copy / paste
+  - [x] Z-index actions
+  - [x] Align / distribute
+- [x] Hotkeys parity (baseline)
+- [x] Inspector
+  - [x] X / Y / W / H
+  - [x] Media `src` live update (image/iframe/video)
+
+### Polish & stability
+- [x] Bounds clamp (keep widgets within the screen bounds)
+- [x] Min sizes (rect min=1; resize logic enforces sane bounds)
+- [x] Avoid stuck context menus (close on normal interactions)
+- [ ] Audit for no-op clickable actions (continue tightening UX)
+
+### “Feels usable”
+- [x] Minimal sample BI screen is included by default (demo widgets preloaded).
+
+## Repo quality gates
+
+Before pushing changes, keep these green:
+```bash
+pnpm -r lint && pnpm -r typecheck && pnpm -r build
+```