npm - @21stware/rpui - Versions diffs - 0.2.1 → 0.3.1 - Mend

@21stware/rpui 0.2.1 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (17) hide show

package/dist/serve/cli.d.ts ADDED Viewed

	@@ -0,0 +1 @@
1	+ export {};

package/dist/serve.js ADDED Viewed

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+import { createServer } from "node:http";
+import { existsSync, statSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, join, resolve, sep, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname$1 = dirname(fileURLToPath(import.meta.url));
+const GALLERY_JS = join(__dirname$1, "gallery.js");
+function collectRpml(dir) {
+  const out = [];
+  const walk = (d) => {
+    for (const name of readdirSync(d)) {
+      if (name.startsWith(".") || name === "node_modules") continue;
+      const full = join(d, name);
+      const st = statSync(full);
+      if (st.isDirectory()) walk(full);
+      else if (/\.rpml$/i.test(name)) {
+        out.push({ path: relative(dir, full).split(sep).join("/"), source: readFileSync(full, "utf8") });
+      }
+    }
+  };
+  walk(dir);
+  return out.sort((a, b) => a.path.localeCompare(b.path));
+}
+function escapeHtml(s) {
+  return s.replace(/[&<>]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;" })[c]);
+}
+function buildHtml(dir, title, galleryJs) {
+  const docs = collectRpml(dir);
+  const data = JSON.stringify(docs).replace(/<\/script/gi, "<\\/script").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+  return `<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<title>${escapeHtml(title)}</title>
+<style>html,body{margin:0;height:100%}</style>
+</head>
+<body>
+<script>globalThis.__RPML_DOCS__ = ${data};<\/script>
+<script type="module">
+${galleryJs}
+<\/script>
+</body>
+</html>
+`;
+}
+function parseArgs(argv) {
+  let dir = ".";
+  let port = 3e3;
+  let host = "localhost";
+  let sawPositional = false;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-p" || a === "--port") port = Number(argv[++i]) || port;
+    else if (a === "--host") host = argv[++i] || host;
+    else if (a === "-h" || a === "--help") usage();
+    else if (!a.startsWith("-") && !sawPositional) {
+      dir = a;
+      sawPositional = true;
+    }
+  }
+  return { dir, port, host };
+}
+function usage() {
+  console.error(`Usage: rpui serve [dir] [--port 3000] [--host localhost]
+Host a directory of .rpml files as one navigable gallery.
+  dir            directory to serve (default: current directory)
+  -p, --port     port (default 3000; auto-increments if busy)
+      --host     host (default localhost)`);
+  process.exit(1);
+}
+function listen(server, port, host) {
+  return new Promise((res, rej) => {
+    const onError = (err) => {
+      if (err.code === "EADDRINUSE" && port < 65535) {
+        server.listen(++port, host);
+      } else {
+        rej(err);
+      }
+    };
+    server.on("error", onError);
+    server.listen(port, host, () => {
+      server.off("error", onError);
+      res(port);
+    });
+  });
+}
+async function serve(argv) {
+  const { dir, port, host } = parseArgs(argv);
+  const root = resolve(dir);
+  if (!existsSync(root) || !statSync(root).isDirectory()) {
+    console.error(`✗ Not a directory: ${dir}`);
+    process.exit(1);
+  }
+  if (!existsSync(GALLERY_JS)) {
+    console.error(`✗ Missing runtime bundle (gallery.js). Reinstall @21stware/rpui or run the build.`);
+    process.exit(1);
+  }
+  const galleryJs = readFileSync(GALLERY_JS, "utf8");
+  const title = root.split(sep).pop() || "RPML";
+  const server = createServer((req, res) => {
+    const url = (req.url || "/").split("?")[0];
+    try {
+      if (url === "/" || !url.endsWith(".rpml")) {
+        res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+        res.end(buildHtml(root, title, galleryJs));
+        return;
+      }
+      const file = join(root, decodeURIComponent(url.replace(/^\/+/, "")));
+      if (file.startsWith(root) && existsSync(file)) {
+        res.writeHead(200, { "content-type": "text/plain; charset=utf-8" });
+        res.end(readFileSync(file));
+      } else {
+        res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+        res.end("Not found");
+      }
+    } catch (e) {
+      res.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
+      res.end("Error: " + e.message);
+    }
+  });
+  const actualPort = await listen(server, port, host);
+  const count = collectRpml(root).length;
+  const addr = `http://${host}:${actualPort}`;
+  console.log(``);
+  console.log(`  RPUI serving ${count} .rpml file${count === 1 ? "" : "s"} from ${root}`);
+  console.log(``);
+  console.log(`  Local:  ${addr}`);
+  console.log(``);
+  console.log(`  Press Ctrl+C to stop`);
+}
+const [sub, ...rest] = process.argv.slice(2);
+if (sub === "serve") {
+  serve(rest);
+} else if (sub === "-h" || sub === "--help" || sub === void 0) {
+  usage();
+} else {
+  console.error(`Unknown command: ${sub}
+`);
+  usage();
+}

package/package.json CHANGED Viewed

@@ -1,46 +1,38 @@
 {
   "name": "@21stware/rpui",
-  "version": "0.2.1",
-  "description": "Rapid Prototype UI: static UI prototype canvas and snapshot primitives implemented as Web Components.",
+  "version": "0.3.1",
+  "description": "RPUI: static UI prototype renderer (RPML Web Components runtime)",
   "type": "module",
   "main": "dist/rpui.js",
   "module": "dist/rpui.js",
   "types": "dist/rpui.d.ts",
+  "bin": {
+    "rpui": "dist/serve.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/rpui.d.ts",
       "default": "./dist/rpui.js"
     },
     "./dist/rpui.js": "./dist/rpui.js",
-    "./llms.txt": "./llms.txt",
-    "./SKILL.md": "./SKILL.md"
+    "./llms.txt": "../../llms.txt",
+    "./SKILL.md": "../../SKILL.md"
   },
   "sideEffects": true,
   "files": [
-    "dist",
-    "llms.txt",
-    "SKILL.md",
-    "README.md",
-    "LICENSE"
+    "dist"
   ],
   "scripts": {
-    "dev": "vite --open /preview/",
+    "dev": "vite --open /preview/ --config vite.config.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "build:js": "vite build",
+    "build:js": "vite build --config vite.config.ts && vite build --config vite.gallery.config.ts && vite build --config vite.serve.config.ts",
     "build:types": "tsc -p tsconfig.types.json",
-    "build": "npm run clean && npm run typecheck && npm run build:js && npm run build:types",
-    "release": "npm run build",
-    "clean": "rm -rf dist && mkdir -p dist"
+    "build": "bun run clean && bun run typecheck && bun run build:js && bun run build:types",
+    "clean": "rm -rf dist && mkdir -p dist",
+    "release": "bun run build"
   },
-  "keywords": [
-    "web-components",
-    "prototype",
-    "ui",
-    "snapshot",
-    "llm"
-  ],
-  "license": "UNLICENSED",
   "devDependencies": {
+    "rpml-parser": "workspace:*",
     "typescript": "^5.8.3",
     "vite": "^5.4.11"
   }

package/LICENSE DELETED Viewed

@@ -1,20 +0,0 @@
-Copyright (c) 2026 21st Ware. All Rights Reserved.
-PROPRIETARY AND CONFIDENTIAL
-This software and its source code are the proprietary and confidential
-property of the copyright holder. No part of this software, in source or
-compiled form, may be copied, reproduced, modified, published, uploaded,
-posted, transmitted, distributed, sublicensed, or otherwise exploited in
-any way, in whole or in part, without the prior express written permission
-of the copyright holder.
-Unauthorized copying, distribution, or modification of this software, via
-any medium, is strictly prohibited.
-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
-COPYRIGHT HOLDER 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/SKILL.md DELETED Viewed

@@ -1,279 +0,0 @@
-# RPUI Prototype Implementation Skill
-Use this skill when converting product requirements, screenshots, existing UI code, or design notes into a static RPUI prototype.
-## Goal
-Produce one readable, static, self-contained HTML prototype that **completely** exposes a product page's UI structure, interaction states, permissions, loading/empty/error/validation states, state machines, and edge cases — at a level of detail engineering can implement from and QA can derive test cases from, without running the real app.
-RPUI does not simulate interaction. It bakes time-based behavior into a spatial document: every state that would normally appear only after a click, a role change, or a server response is laid out at once. The two words that govern quality are **complex** (cover the real information density of a production page) and **complete** (no state, branch, permission, or edge case left implicit).
-> If a reviewer finishes reading your prototype and still has to ask "but what happens when…", the prototype is not done.
-## Complexity expectation
-A realistic complex application page is **not** a few annotated regions. Calibrate to this baseline:
-- **8–10 top-level annotations** (`<rp-annotation id="N">`), one per meaningful pinned region.
-- **3–5 levels of annotation nesting** where the domain warrants it: region → element → state family → per-state rule → boundary/exception.
-- **Every conditional branch enumerated** with `<rp-enum>` — states, permission variants, validation outcomes, async results.
-- Annotation bodies written at **implementation depth**: trigger conditions, data source, state-machine transitions, permission gates, validation rules, error handling, boundary values.
-`demo/golden.html` is the reference for this bar. Study it before authoring. The minimal template at the bottom of this file shows mechanics only — never treat it as a complexity target.
-## Required inputs
-Prefer these inputs, in priority order:
-1. Product requirement or user story.
-2. Screenshot or design draft.
-3. Existing code with conditional rendering (read `v-if`/`&&`/ternaries/guards — each is a state to enumerate).
-4. Permission matrix or role notes.
-5. Known loading, empty, error, validation, and edge cases.
-If inputs are missing, infer common SaaS/product states and make every assumption explicit in an annotation. Never silently omit a plausible state.
-## Output contract
-Output a complete HTML file that imports exactly one RPUI runtime file:
-```html
-<script type="module" src="./dist/rpui.js"></script>
-```
-The document must contain:
-1. one `<rp-page>` root with `title`, `route`, and `description` (the description should state which representative state the main snapshot captures),
-2. exactly one `<rp-main-view>` containing the main page snapshot,
-3. snapshot content built with `rp-*` primitives only,
-4. numbered `data-pin="N"` anchors on every meaningful main-view region,
-5. matching top-level `<rp-annotation id="N" label="...">` blocks,
-6. `<rp-enum>` / `<rp-enum-item>` for every conditional branch and state family.
-## The recursive decomposition method
-This is the core technique for reaching completeness. Decompose every pinned region top-down through up to five semantic levels. Stop at the level where further splitting adds no implementation value.
-- **L1 — Region** (`<rp-annotation id="N">`, pinned): a structural area of the page (navbar, sidebar, filter bar, table, drawer). One per `data-pin`.
-- **L2 — Element / concern** (nested `<rp-annotation>`): a distinct responsibility inside the region (search behavior, a single column, the bulk-action bar, one form field group).
-- **L3 — State family** (`<rp-enum>` or a nested annotation containing one): the set of mutually exclusive states for that element (default/focus/filled/error; collapsed/expanded; the rows' read×SLA×selected matrix).
-- **L4 — Per-state rule** (`<rp-enum-item>` + `description`, or a deeper annotation): what each state _means_ and the rule behind it — trigger, threshold, transition, gate.
-- **L5 — Boundary / exception** (deepest annotation/enum): extremes and failure modes — 0/empty/overflow values, race conditions, permission denials, irreversible actions.
-Not every region needs all five levels. A simple stat card may stop at L3. A data table with a detail drawer will routinely reach L5. Let the domain decide depth; let completeness decide breadth.
-## Annotation content structure
-L1/L2 annotation bodies must read like a spec, not a caption. For a non-trivial region, cover the relevant subset of these dimensions in plain prose:
-- **Trigger / entry condition** — what causes this to appear or activate.
-- **Data source & refresh** — where values come from, polling/refresh cadence.
-- **State enumeration** — which states exist (then expand them in `<rp-enum>`).
-- **Permission gate** — which roles see/use it, what changes per role.
-- **Validation rule** — required fields, formats, cross-field constraints.
-- **Error / async handling** — loading, empty, partial-failure, retry behavior.
-- **Boundary values** — limits, overflow, truncation, zero/critical states.
-Keep each dimension to one or two precise sentences. "Compact" means no padding and no waffle — it does **not** mean omitting a dimension that matters. Completeness wins over brevity; precision wins over length.
-## Coverage matrix method
-Completeness in complex apps is combinatorial, not a flat list. When two or more axes interact, enumerate the product, not each axis alone:
-- **permission × state** — e.g. detail-drawer buttons differ by role _and_ by ticket status.
-- **role × data-size** — admin view of 5000 rows vs agent view of 7 rows.
-- **flow-step × validation** — each wizard step × (valid / invalid / pending).
-- **read-state × SLA × selection** — a table row's appearance is the product of all three.
-Build the matrix mentally, drop impossible cells, and create one `<rp-enum-item>` for each surviving combination. If a cell is intentionally out of scope, say so in an annotation rather than leaving it blank.
-## Implementation steps
-1. Identify route, title, and a one-sentence description naming the representative state the snapshot captures.
-2. Choose a device preset: `web` desktop/admin, `ipad` tablet, `mobile` phone. Prefer fixed-width, auto-height.
-3. Choose the **most information-dense representative state** for the main snapshot: loaded data, an active selection, an open drawer/expanded panel central to the page, role-specific controls, active validation. The snapshot should look like the page on a busy day, not an empty shell.
-4. Build the snapshot inside `<rp-main-view device="…">` using only `rp-*` primitives, usually inside `<rp-viewport device="…">`.
-5. Add `data-pin="N"` to every meaningful region. Number from 1, no gaps.
-6. For every pin create one top-level `<rp-annotation id="N" label="…">`.
-7. Apply the recursive decomposition method to each region (L1→L5 as warranted).
-8. For every conditional branch, build a coverage matrix and expand it with `<rp-enum>` / `<rp-enum-item label="…" description="…">`.
-9. Write annotation bodies at implementation depth using the content-structure dimensions.
-10. Verify no interactive JS, event attributes, external images, external CSS, or CDN icons are used.
-## Section addressing, markers & deep links
-The runtime auto-assigns a `data-rp-section` path to every annotation: top-level = its `id` (e.g. `3`); nested = parent path + 1-based sibling index (e.g. `3-2`, `3-2-1`). Authors do not write these.
-Every annotation also gets a **marker showing its local index** (the last segment of its section path):
-- Top-level (has `id`): blue water-drop showing the id (`1`, `2`, …), matching its pin.
-- Nested depth 1: purple circle showing its local index (`3-2` shows **2**).
-- Nested depth ≥2: green triangle showing its local index (`3-2-1` shows **1**).
-So a nested annotation at `1-1` is marked simply **1** — the number is local to its parent, not the full path. This lets you annotate a UI slice one level deeper and still reference it unambiguously ("see ① under 区域 3").
-- Clicking a pin, or any annotation title, updates the URL `?section=<path>` and scrolls/focuses that annotation (dashed outline).
-- Opening a URL with `?section=3-2-1` focuses that nested annotation on load.
-- `<rp-enum-item>` cards are auto-numbered with a black square index badge (1, 2, 3…) so prose can refer to "state 2".
-Use stable, intentional nesting order — index-based addresses and markers depend on sibling order.
-### Annotating a UI slice further
-When a UI slice rendered inside an annotation needs its own explanation, do not flatten it into prose. Nest another `<rp-annotation>` around or after the slice: it receives its own numbered marker (circle/triangle) and its body indents one level. The chain reads:
-```
-main view  →  ⬤ annotation 1 (pinned)  →  UI slice  →  ① nested annotation (marked "1")  →  detail
-```
-Example — a slice that itself has sub-rules:
-```html
-<rp-annotation id="3" label="筛选区">
-  触发条件、数据来源……
-  <rp-enum>
-    <rp-enum-item label="展开浮层"><rp-select state="expanded" options="全部,P1,P2"></rp-select></rp-enum-item>
-  </rp-enum>
-  <rp-annotation label="排序规则">      <!-- marked ① (purple circle), indented -->
-    点击列头切换升/降序，默认按 SLA 剩余时间升序。
-    <rp-annotation label="多列排序">    <!-- marked ① (green triangle), indented again -->
-      按住 Shift 点击追加次级排序键。
-    </rp-annotation>
-  </rp-annotation>
-</rp-annotation>
-```
-## Mid-level composition patterns
-Complex pages are built from recurring composite modules. Assemble these from primitives rather than reinventing per page:
-- **Data table module**: `rp-tabs` (status filter) + filter row (`rp-select`/`rp-date-picker`/`rp-toggle`) + `rp-bulk-action-bar` + `rp-table` (`has-checkbox has-action`) + `rp-pagination`.
-- **Master–detail**: `rp-layout columns="minmax(0,1fr) <w>"` with the list on the left and a detail panel on the right. If the detail panel opens on row click (transient), apply the overlay trigger pattern; only keep it open in the snapshot when it is a permanently docked region.
-- **Dashboard header**: `rp-layout columns="repeat(N,1fr)"` of `rp-stat-card`.
-- **Multi-step flow**: `rp-steps` + per-step `rp-form` / `rp-form-item`, each step's validation enumerated.
-- **Form with validation**: `rp-form` + `rp-form-item label required error` + control in `error`/`filled` states enumerated side by side.
-## Component families
-RPUI ships a broad primitive set. Pick the smallest primitive that conveys the intent. See `llms.txt` for the full attribute reference; for a visual catalog of every component and its states, run `npm run dev` and open the source-mode preview at `/preview/`.
-- **Layout**: viewport, layout, panel, card, split-pane, divider, spacer, sidebar, navbar.
-- **Data input**: input, search, textarea, select, date-picker, checkbox, radio, toggle, slider, range, number-input, rating, pin-input, color-swatch, autocomplete, upload, button, button-group, form, form-item.
-- **Data display**: table, table-row, list, list-item, tree, timeline, calendar, kanban, code-block, diff, image-grid, key-value, accordion, stat-card, tag, chip, badge, avatar, image-placeholder, progress.
-- **Navigation**: tabs, breadcrumb, pagination, steps, segmented, menu, context-menu, command-palette, toc, kbd.
-- **Feedback / overlays**: alert, toast, banner, empty, loading, skeleton, countdown, result, progress, tooltip, dropdown, popover, modal, drawer.
-- **Enterprise / SaaS**: permission-gate, quota-bar, api-key, audit-row, workflow-node.
-### Platform primitives (Apple HIG)
-For native-feeling iOS / macOS prototypes, prefer the platform-prefixed primitives over the generic web ones:
-- **iOS** (`rp-ios-*`): ios-navbar, ios-tabbar, ios-list / ios-list-item, ios-action-sheet, ios-alert, ios-switch, ios-segmented, ios-button, ios-search, ios-stepper. Use with `device="mobile"`.
-- **macOS** (`rp-macos-*`): macos-window, macos-toolbar, macos-menubar, macos-sidebar / macos-source-item, macos-segmented, macos-popover, macos-sheet, macos-stepper, macos-disclosure, macos-table. Use with `device="web"`.
-Choose the platform that matches the product: a generic web SaaS page uses the plain `rp-*` set; a native iOS app uses `rp-ios-*` inside a `device="mobile"` viewport; a native macOS app wraps content in `rp-macos-window`. Do not mix platform styles within one snapshot.
-> ARIA note: component states (checked/expanded/selected/disabled/current) mirror the structure ARIA APG expects, so annotations can describe accessibility intent. RPUI stays static and does **not** emit runtime `role`/`aria-*` — treat ARIA as a design reference for *which states to document*, not as something the runtime manages.
-## Overlay trigger pattern (critical)
-Overlays and transient feedback are **interaction results, not page regions**. This includes `rp-modal`, `rp-drawer`, `rp-dropdown`, `rp-popover`, `rp-tooltip`, and `rp-toast`. Do **not** place them in the main snapshot — a snapshot showing an open modal or a live toast is a frozen mid-interaction frame, which contradicts RPUI's "space replaces time" model. Worse, never stack mutually exclusive overlays (empty + loading + modal + toast) side by side in the snapshot as if they coexist.
-Instead, model each overlay as a **trigger → result** pair:
-1. **Pin the trigger** in the main snapshot — the button, row, field, or menu entry that opens the overlay (e.g. an action button, a table row, a `…` menu). The snapshot shows only this resting trigger.
-2. **State the trigger condition** in the annotation body: what action or system event opens it, any precondition, and the permission gate.
-3. **Render the overlay inside the annotation**, normally as an `<rp-enum>` showing the closed→open transition or the overlay's own variants (e.g. confirm vs. irreversible, success vs. partial-failure vs. error toast).
-```html
-<!-- main snapshot: only the trigger is pinned -->
-<rp-button label="批量关闭" variant="danger" data-pin="5"></rp-button>
-<!-- annotation: trigger condition + overlay rendered here -->
-<rp-annotation id="5" label="批量关闭">
-  触发条件：勾选 ≥1 行后点击「批量关闭」，仅主管/坐席可见。点击弹出二次确认。
-  <rp-enum>
-    <rp-enum-item label="确认弹窗" description="列出影响范围与可逆性。">
-      <rp-modal title="批量关闭确认" has-footer>
-        <rp-alert type="warning" title="将关闭 3 条工单" message="客户 7 天内可重开。"></rp-alert>
-      </rp-modal>
-    </rp-enum-item>
-    <rp-enum-item label="关闭成功" description="3s 自动消失，列表刷新。">
-      <rp-toast type="success" title="已关闭 3 条工单"></rp-toast>
-    </rp-enum-item>
-  </rp-enum>
-</rp-annotation>
-```
-Narrow exception: when a side panel is a **permanently docked structural region** of the page (not a transiently opened overlay), it may appear open in the snapshot as the representative state — but its open/close trigger and conditions must still be documented in its annotation. When unsure, treat it as an overlay and use the trigger pattern.
-## Authoring rules
-- Use `rp-*` tags for new work. `proto-*` and `snap-*` are compatibility aliases only.
-- Use `<rp-page>` as root; exactly one `<rp-main-view>` per page.
-- Use `rp-*` primitives for both the snapshot and UI slices inside annotations. Never use raw `div`/`button`/`input`/`table` for product UI; plain text and simple inline markup in annotations is fine.
-- No CSS or JS in the prototype; no `position:absolute`/`fixed` in snapshot content (RPUI owns pin positioning).
-- Do not hide important content behind interactions — expand it into `<rp-enum>`.
-- Overlays and transient feedback (`rp-modal`, `rp-drawer`, `rp-dropdown`, `rp-popover`, `rp-tooltip`, `rp-toast`) are interaction results: do not place them in the main snapshot. Pin the trigger and render the overlay inside its annotation (see Overlay trigger pattern). Plain collapsed `rp-select` in the snapshot is fine; its expanded list belongs in an annotation enum.
-- Note runtime limits honestly: `rp-table` cell text is sampled by the runtime from column names — for exact data, describe it in the annotation rather than expecting the table to render it.
-## Multi-page applications
-One `<rp-page>` = one screen. For an application with several screens:
-- Produce one RPUI HTML file per screen; name files by route.
-- If a single page exceeds ~12 pins, it is too dense — split a sub-area into its own page and note in the description that it details a region of the parent.
-- For cross-screen flows (wizard, drill-down), state the entry/exit routes in each page's description so the set reads as a connected flow.
-## Minimal template (mechanics only — not a complexity target)
-```html
-<!doctype html>
-<html lang="zh-CN">
-  <head>
-    <meta charset="UTF-8" />
-    <script type="module" src="./dist/rpui.js"></script>
-  </head>
-  <body>
-    <rp-page title="页面标题" route="/route" description="主快照取『…』代表态">
-      <rp-main-view device="web" scale="0.65">
-        <rp-viewport device="web">
-          <!-- main snapshot -->
-        </rp-viewport>
-      </rp-main-view>
-      <rp-annotation id="1" label="区域说明">
-        触发条件、数据来源、权限与校验在此用一两句说清。
-        <rp-enum>
-          <rp-enum-item label="默认" description="正常数据态。"
-            ><rp-empty label="示例"></rp-empty
-          ></rp-enum-item>
-          <rp-enum-item label="加载中" description="首次进入或刷新。"
-            ><rp-loading rows="3"></rp-loading
-          ></rp-enum-item>
-          <rp-enum-item label="错误" description="服务端或网络异常。"
-            ><rp-alert type="error" title="加载失败" message="请重试"></rp-alert
-          ></rp-enum-item>
-        </rp-enum>
-      </rp-annotation>
-    </rp-page>
-  </body>
-</html>
-```
-For a realistic complex page, see `demo/golden.html` (9 top-level annotations, 3–5 levels deep, implementation-level bodies).
-## Quality bar
-A good RPUI prototype is reviewable by engineering, product, design, and QA without running the app. QA derives test cases from annotations; engineering derives conditional-rendering and state-machine logic from enum items; design sees whether any hidden state was missed.
-Before finishing, check:
-- pin numbers continuous; every pin has a matching top-level annotation,
-- the snapshot shows the most information-dense useful state,
-- decomposition reached implementation depth where the domain warranted it (state machines, permission gates, validation, boundaries all covered),
-- combinatorial states (permission × state, role × scale, step × validation) are enumerated, not collapsed,
-- every hidden interaction result is expanded into an enum,
-- role/permission differences are explicit,
-- runtime limits (e.g. table sampling) are noted where they affect fidelity,
-- no forbidden product-UI HTML, scripts, event handlers, or external resources.