@whzxc/agent-design-gallery 0.14.1 → 0.15.0

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 (62) hide show
  1. package/README.md +26 -16
  2. package/package.json +1 -1
  3. package/public/access.css +15 -2
  4. package/public/app.js +708 -483
  5. package/public/arrangement-worker.js +7 -7
  6. package/public/arrangement.js +35 -30
  7. package/public/assets.js +60 -38
  8. package/public/auth.js +59 -4
  9. package/public/boards.js +124 -0
  10. package/public/comment-anchors.js +50 -0
  11. package/public/comments.css +400 -0
  12. package/public/comments.js +1106 -0
  13. package/public/context-menu.js +97 -0
  14. package/public/frame-identity.js +26 -2
  15. package/public/hub.css +25 -3
  16. package/public/hub.html +10 -2
  17. package/public/hub.js +127 -23
  18. package/public/icons.js +2 -0
  19. package/public/index.html +13 -9
  20. package/public/instance-actions.js +9 -2
  21. package/public/layout.js +156 -86
  22. package/public/selection.js +1 -1
  23. package/public/style.css +74 -152
  24. package/public/switcher.css +5 -4
  25. package/public/switcher.js +109 -34
  26. package/public/token-catalog.js +8 -3
  27. package/public/tokens.css +14 -1
  28. package/public/view-route.js +0 -1
  29. package/src/boards/board.mjs +30 -0
  30. package/src/boards/token-board.mjs +196 -0
  31. package/src/cli-output.mjs +8 -5
  32. package/src/cli.mjs +49 -29
  33. package/src/comments.mjs +293 -0
  34. package/src/http.mjs +2 -3
  35. package/src/hub/project-link.mjs +41 -0
  36. package/src/hub/registry.mjs +5 -0
  37. package/src/hub.mjs +14 -10
  38. package/src/link.mjs +13 -1
  39. package/src/server.mjs +57 -93
  40. package/src/service.mjs +46 -12
  41. package/src/toolkit/arch.mjs +3 -2
  42. package/src/toolkit/asset-rules.mjs +24 -1
  43. package/src/toolkit/commands.mjs +12 -7
  44. package/{public/review.js → src/toolkit/diff-document.mjs} +137 -43
  45. package/src/toolkit/diff-inputs.mjs +66 -30
  46. package/src/toolkit/diff.mjs +181 -39
  47. package/src/toolkit/impact-selection.mjs +25 -10
  48. package/src/toolkit/impact.mjs +32 -12
  49. package/src/toolkit/move-pairing.mjs +140 -0
  50. package/src/toolkit/project-index.mjs +2 -2
  51. package/src/toolkit/results.mjs +1 -1
  52. package/src/toolkit/review-document.mjs +435 -0
  53. package/src/toolkit/review-groups.mjs +29 -0
  54. package/src/toolkit/review-observation.mjs +131 -0
  55. package/src/toolkit/review-sheet.mjs +117 -0
  56. package/src/toolkit/review-specimens.mjs +60 -0
  57. package/src/toolkit/review.mjs +140 -0
  58. package/src/toolkit/runtime.mjs +1 -1
  59. package/src/toolkit/theme.mjs +16 -0
  60. package/public/annotations.js +0 -816
  61. package/public/labels.js +0 -122
  62. package/src/annotations.mjs +0 -238
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Agent Design Gallery
2
2
 
3
- Build and browse a repository's TSX design frames with a local browser canvas.
3
+ Build, check and browse a repository's TSX design library as boards in a local viewer or resident multi-project hub. Review changes against Git and discuss them in comment threads pinned to frames.
4
4
 
5
5
  ```sh
6
6
  npm install -g @whzxc/agent-design-gallery
@@ -40,19 +40,17 @@ The stored key prefix changes to `adg_`; update browser access with the new key
40
40
 
41
41
  Drag or scroll to pan. Pinch, or hold Control/Command while scrolling, to zoom around the pointer. Click a frame to select its variant; double-click or press Enter to focus it. Hover an exported component inside a frame to outline its root, then click to inspect its source and export. Arrow keys pan; +/− zoom; 0 fits all; 1 sets the canvas to 100% around the usable canvas center. Escape clears the selection (or closes the current search, dialog or menu). Back returns to the previous selection and camera.
42
42
 
43
- The left toolbar holds Contents, the project picker, scope tabs, and search. **Tokens** appears first when the project provides a token file. A clean project URL opens the first nonempty design layer, normally **Components**. Use the tabs to switch layers or choose **All designs**. Contents starts closed and opens over the canvas. Asset search opens Contents with matches from the current scope. Click a group or asset name to focus it, or use its trailing **Render only** action to open it independently. An isolated asset lists its frames in Contents. Search and Fit all work within the current scope. Back restores the previous scope, selection and camera.
43
+ The left toolbar holds Contents, the project picker, scope tabs, and search. **Tokens** appears first when the project provides a token file. A clean project URL opens the first nonempty design layer, normally **Components**. Use the tabs to switch layers or choose **All designs**. Contents starts closed and opens over the canvas. Asset search opens Contents with matches from the current scope and offers **Search All designs** when a scoped search has no matches. Click a group or asset name to focus it, or use its trailing **Render only** action to open it independently; an isolated-scope pill in the top bar exits back to the layer in one click. An isolated asset lists its frames in Contents. Search and Fit all work within the current scope. Back restores the previous scope, selection and camera.
44
44
 
45
45
  Path links locate a selection within its design hierarchy. Query links open an independent layer, group, source, or frame. Copy the viewer URL to share its current view, or use `adg link` to generate either form for a specific target.
46
46
 
47
47
  ## Share a design update
48
48
 
49
49
  ```sh
50
- adg diff --base=<rev> --impacted --json
51
- adg link https://gallery.example/p/project/ --base=<rev>
52
- adg open ./design --base=<rev> --no-open
50
+ adg review --base=<rev> --json
53
51
  ```
54
52
 
55
- Set `--base=<rev>` to the task's starting commit. Git supplies the added, removed and changed frames. A change report carries one reachable review URL from `adg link <viewer-url> --base=<rev>` and the `added`, `removed` and `changed` counts from `adg diff --base=<rev> --impacted`, with no per-frame images. The hub and direct viewer serve the same review page at `?base=<rev>`, showing counts at the top followed by added, removed and changed frames in both themes (`light` and `dark`) with before, after and difference side by side. Targeted `--asset`, `--frame`, `--group`, `--layer`, `--tokens` and `--mode=path` links remain available for interactive navigation, and `adg render` exports frame PNGs for automation. See the [review handoff workflow](docs/design-toolkit.md#review-handoff).
53
+ Choose the task's starting commit and share the HTML at `data.path`. The file opens offline, renders the frames on demand, and supports enlargement and frame links to the project's ADG boards. The current system theme is the default. Use `--viewer-url` when the project is served by a different hub, or `--exact` to compare every frame scheduled by impact analysis. See the [review handoff workflow](docs/design-toolkit.md#review-handoff).
56
54
 
57
55
  Every command accepts `--json`: finite commands return one versioned envelope, while foreground `open`/`serve` stream NDJSON events. `render` PNGs are in `data.captures`, with CSS and PNG pixel dimensions. See the [agent CLI interface](docs/agent-interface.md) for schemas, exits and recovery actions.
58
56
 
@@ -70,17 +68,17 @@ The bottom zoom bar holds Back, zoom out, the zoom menu, zoom in, Fit, and Minim
70
68
 
71
69
  Design sources are TSX files directly in `design/components/`, `design/modules/` and `design/surfaces/`. Default discovery also includes `design/studies/` once it contains a direct TSX study; explicit `sources` lists remain unchanged. Fixtures and artwork stay in their supporting directories. Import `Frame` and `Icon` from `adg`, export reusable component functions, and default-export a function returning the declared frames. JSX builds static HTML and inline SVG without React or browser scripts. Tailwind v4 utilities resolve through the project's `design/tokens.css`; light and dark are selected by the document's `data-theme`.
72
70
 
73
- Choose the **Tokens** tab to inspect the current project's `design/tokens.css`. Filter by category in Contents or search the table by name or value from the toolbar, compare light and dark declarations side by side, and click a token name to copy it. Colors show swatches, and pixel values for spacing, sizes, and radii show a visual sample. Share `?scope=tokens` to open the catalog directly.
71
+ Choose the **Tokens** tab to inspect the current project's `design/tokens.css`. The Tokens board presents paired light/dark colour swatches, typography, shape, elevation, sizing and motion samples, with click-to-copy token names and a top-bar toggle to switch to the list view. Typing in search filters the list view directly and returns to the board when cleared. Share `?scope=tokens` to open the board directly.
74
72
 
75
73
  Follow the [design asset rules](docs/asset-rules.md) for placement, ownership, states, frame names, fidelity, lifecycle and studies. The [adoption guide](docs/asset-rules.md#adopting-an-existing-project) covers inventory, a read-only audit with `file / problem / suggested fix` findings, check-decided governance steps, the implementation checks a consumer adds, and the mappings/governance each consumer keeps locally. `sources` orders production layers from lower to higher; `check` reports upward imports. Set `check: { importDirection: false }` to opt out of that lint while keeping frame checks.
76
74
 
77
- A component source is one set: frames run in source order with 32px gaps, wrap before 1600px, and have 48px between rows. Sets pad forms by 24px at the sides and bottom and 36px at the top. A surface source is one flow: each frame receives 16px padding and follows the flow layout. Frame notes appear in the inspector, outside the drawing. Full sheet has been removed; choose a declared form or frame.
75
+ Each chapter is one board at any height, including in the Surfaces layer. Each source is a section with its declared frames in order, shown at their rendered sizes on captioned wells in a 12-column grid. Boards start at 1680px wide and grow for wider specimens. Headers, source labels, frame names, notes and proposal markers scale with the camera. See the [board contract](docs/boards.md) for dimensions and presentation.
78
76
 
79
77
  Legacy SVGs remain browsable with their existing geometric crops and relative embedded artwork. Files without declarations keep a whole-file preview. New toolkit commands accept TSX only; an SVG directly in `design/components/` or `design/surfaces/` must be converted. Imported SVG artwork belongs in `design/art/`; PNG, JPEG and WebP imports become data URLs. Add `?url` to an import under `design/art/` to embed any file as a data URL, including self-contained SVG previews.
80
78
 
81
- Sets and flows pack into sections, and sections into a stable world. Saving a source, imported component, artwork or tokens refreshes affected previews without moving the camera. Unchanged regions retain their positions; new or enlarged regions move below existing content. Use Arrange current group to compact after structural changes. Labels retain constant screen sizes and hide when they collide with chrome or other labels.
79
+ Boards flow in chapter order into the shortest column, using the leftmost column on ties. Column count targets a 16:10 layer band, with 240px between columns and boards and 480px between layers. Saving a source refreshes its board and moves boards below it in the same column by its height change while keeping the camera. **Arrange current group** recomputes column assignment.
82
80
 
83
- Files group by directory unless `gallery.json` supplies project groups. Entries must point directly into configured source directories:
81
+ Files group by directory unless `gallery.json` supplies chapters, with each title naming a board and each listed source becoming a section in order. Entries must identify configured source entries, including a module folder's `index.tsx`:
84
82
 
85
83
  ```json
86
84
  {
@@ -91,7 +89,9 @@ Files group by directory unless `gallery.json` supplies project groups. Entries
91
89
  }
92
90
  ```
93
91
 
94
- Unlisted assets remain in directory groups. Projects own their TSX sources, artwork, tokens, configuration, and Git history. Theme, sidebar, inspector, and per-directory camera and selection preferences stay in `~/.agent-design-gallery/state.json`, defaulting to `~/.agent-design-gallery/state.json`. Refreshing or reopening a directory restores its zoom, position, selected component and form. Canvas asset headings show the source's last modification time in local time; hover for the complete timestamp. `--state-dir` isolates preferences.
92
+ Unlisted sources form directory chapters. A mixed-layer group splits into a same-titled chapter in each layer view; keep project groups within one layer. A module folder shows its `index.tsx` under the feature directory name. Projects own their TSX sources, artwork, tokens, configuration and Git history. Preferences stay in `~/.agent-design-gallery/state.json`; `--state-dir` isolates them. Refreshing or reopening a directory restores its camera and selection. Source labels show modification times.
93
+
94
+ [Comments](docs/comments.md) are threads pinned to the library. Open a frame from the standalone review to discuss it on the board.
95
95
 
96
96
  ## Design toolkit
97
97
 
@@ -120,7 +120,7 @@ Builds produce standalone HTML and renders produce `<frame>-light.png` and `<fra
120
120
  `adg diff --base=<rev>` overwrites `<configured output>/diff` and writes a self-contained
121
121
  `index.html` review page, per-frame/theme before, after and difference PNGs, plus
122
122
  `report.json` for Git and working-tree sources, including added/removed frames. `index.html`
123
- shows the `added`, `removed` and `changed` frame counts (`data.review`) at the top, followed
123
+ shows the `added`, `removed`, `moved` and `changed` frame counts (`data.review`) at the top, followed
124
124
  by each affected frame in both themes with before, after and difference side by side. Existing
125
125
  frames require exact pixels and size. New part Frames can declare `parent` and use
126
126
  consumer `diff.thresholds`; a `structural` batch requires full existing-frame coverage
@@ -197,7 +197,7 @@ adg serve --port 4310
197
197
 
198
198
  Root commands output JSON. `--state-dir <path>` isolates registry and preferences. Scans run on add and explicit CLI/web rescan only. Depth defaults to 2 and accepts 0–3; hidden directories, node_modules, symlinks and Git worktrees (`.git` is a file) are skipped. Only directories containing `adg.config.mjs`, `.js` or `.ts` are projects. TypeScript configs load through esbuild.
199
199
 
200
- The hub binds 127.0.0.1. `GET /api/projects` returns name, path, design directory, stable slug and `/p/<slug>/` route, branch, short HEAD, last design commit time and dirty flag, source count and version compatibility. `frameCount` is null until an active viewer has built every source, then reports the exact count. Config errors are returned per project. `GET /api/roots` lists roots; `POST /api/rescan` rescans registered roots with no path input. Project viewers start on demand and stop after five idle minutes; an open SSE stream keeps a viewer active. The initial hub page is intentionally unstyled pending design approval.
200
+ The hub binds 127.0.0.1. `GET /api/projects` returns name, path, design directory, stable slug and `/p/<slug>/` route, branch, short HEAD, last design commit time and dirty flag, source count and version compatibility. `frameCount` is null until an active viewer has built every source, then reports the exact count. Config errors are returned per project. `GET /api/roots` lists roots; `POST /api/rescan` rescans registered roots with no path input. Project viewers start on demand and stop after five idle minutes; an open SSE stream keeps a viewer active. The hub home lists registered projects and live instances, adding instant search once five or more destinations exist.
201
201
 
202
202
  ### Access keys and instances
203
203
 
@@ -209,7 +209,7 @@ adg serve --rotate-key # Replace the key and exit
209
209
  adg serve --rotate-key --print-key # Replace and print it
210
210
  ```
211
211
 
212
- Rotation applies to new requests in a running hub immediately. Existing streams end when disconnected. Open the hub or a canonical viewer URL with `?key=adg_...` once: the public HTML/JS shell stores the key in localStorage (`adg-key`) and removes the parameter using history.replaceState. There is no cookie or authentication redirect. Shells contain no project data. Data requests use `Authorization: Bearer <key>`; the server also accepts `X-ADG-Key` and `?key=`. SSE uses a query key. Frames, SVGs and artwork are fetched with headers and become self-contained blob/data previews. Missing or invalid credentials return JSON 401 and the shell shows a minimal 401 state.
212
+ Rotation applies to new requests in a running hub immediately. Existing streams end when disconnected. Open the hub or a canonical viewer URL with `?key=adg_...` once, or paste the key (or `?key=` URL) directly into the 401 access card: the public HTML/JS shell stores the key in localStorage (`adg-key`) and removes any URL parameter using history.replaceState. There is no cookie or authentication redirect. Shells contain no project data. Data requests use `Authorization: Bearer <key>`; the server also accepts `X-ADG-Key` and `?key=`. SSE uses a query key. Frames, SVGs and artwork are fetched with headers and become self-contained blob/data previews. Missing or invalid credentials return JSON 401 and the shell shows the 401 key-entry card.
213
213
 
214
214
  `adg open` registers itself in `<state>/instances/<id>.json` and removes its record on exit, independently of whether a hub is running. `GET /api/health` returns `{ id, capabilities: { keyAuth: 1 } }`. `GET /api/instances` checks PID liveness and the health ID, pruning dead or mismatched records. An alive PID with missing health or a viewer without the key-auth capability remains listed as not proxyable. Records include pid, port, directory, project name, branch, worktree flag, start time and ADG version.
215
215
 
@@ -245,12 +245,22 @@ The proxy_pass has no URI suffix; do not strip `/p/<slug>/` or `/i/<id>/`. Disab
245
245
  ### macOS resident service
246
246
 
247
247
  ```sh
248
- adg service install [--port 4310] [--state-dir /absolute/state/path]
248
+ adg service install [--port 4310] [--state-dir /absolute/state/path] [--public-origin https://design.example.com]
249
249
  adg service status
250
250
  adg service logs
251
251
  adg service uninstall
252
252
  ```
253
253
 
254
- The LaunchAgent `org.agent-design-gallery.hub` starts the resident hub at login with RunAtLoad and keeps it running with KeepAlive. It binds loopback and uses the same registry/key and auth contract as `adg serve`. Installation records absolute Node and CLI paths in `~/Library/LaunchAgents/org.agent-design-gallery.hub.plist`, so launchd needs no shell PATH. Reinstall after moving the CLI or replacing the recorded Node installation.
254
+ The LaunchAgent `org.agent-design-gallery.hub` starts the resident hub at login with RunAtLoad and keeps it running with KeepAlive. It binds loopback and uses the same registry/key and auth contract as `adg serve`. Installation records absolute Node and CLI paths in `~/Library/LaunchAgents/org.agent-design-gallery.hub.plist`, so launchd needs no shell PATH. Reinstall after moving the CLI or replacing the recorded Node installation. The public origin sets the base for comment links and is retained on subsequent installs.
255
255
 
256
256
  `status` prints JSON with installed/loaded state, PID, plist and log paths. `logs` prints the last 200 lines of each log. stdout and stderr go to `service.stdout.log` and `service.stderr.log` in the state directory. After an install with a custom state directory, status/logs/uninstall recover that directory from the plist when no override is given. Uninstall unloads the job and removes its plist, retaining registry, key, preferences and logs. Service commands on other platforms return an explicit unsupported error; `adg serve` remains available there.
257
+
258
+ ### Review handoff
259
+
260
+ `adg review` compares the resolved Git base against the current working tree and writes one HTML file. Frames are grouped by direct and inherited change. Each inherited group starts with the median-area representative and its outliers, and expands to show every member. Before and After are rendered as native document content; the Difference pane shows the pixel diff. Click a preview to enlarge it or a frame title to open its source on a registered ADG board.
261
+
262
+ The default hybrid pass uses equal rendered structure to skip screenshots for supported frames, and runs the pixel comparison for the rest. Use `adg review --exact` when pixel-equivalent review coverage is required. `adg diff` exposes exact comparison artifacts and verdicts for automation.
263
+
264
+ `adg check` emits non-failing chapter warnings for component/module sources outside
265
+ `gallery.json` chapters (`CHAPTER_SOURCES_UNASSIGNED`) and chapters above 12 sources
266
+ (`CHAPTER_TOO_LARGE`). Organize chapters by feature, usually 3 to 12 sources each.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@whzxc/agent-design-gallery",
3
- "version": "0.14.1",
3
+ "version": "0.15.0",
4
4
  "description": "Local TSX design toolkit and SVG viewer",
5
5
  "type": "module",
6
6
  "license": "MIT",
package/public/access.css CHANGED
@@ -1,10 +1,23 @@
1
- .access-shell { position:fixed; inset:0; display:flex; flex-direction:column; padding:12px; background:var(--canvas); color:var(--text); font:13px/1.5 var(--font-ui); overflow:auto; }
1
+ .access-shell { position:fixed; inset:0; display:flex; flex-direction:column; padding:12px; background:var(--canvas); color:var(--text); font:var(--text-body)/1.5 var(--font-ui); overflow:auto; }
2
2
  .access-shell * { box-sizing:border-box; }
3
+ .access-shell [hidden] { display:none!important; }
3
4
  .access-brand { align-self:flex-start; display:flex; align-items:center; height:44px; padding:6px 14px; border-radius:var(--radius-panel); background:var(--surface); box-shadow:var(--shadow-float); font-size:var(--text-section); font-weight:650; }
4
5
  .access-center { display:flex; flex:1; align-items:center; justify-content:center; }
5
6
  .access-card { width:360px; max-width:100%; padding:24px; display:flex; flex-direction:column; gap:20px; background:var(--surface); border-radius:var(--radius-panel); box-shadow:var(--shadow-float); }
6
7
  .access-code { display:flex; align-items:center; justify-content:space-between; color:var(--text-tertiary); }
7
- .access-code span { font:12px/1.5 var(--font-mono); }
8
+ .access-code span { font:var(--text-meta)/1.5 var(--font-mono); }
8
9
  .access-copy { display:flex; flex-direction:column; gap:8px; }
9
10
  .access-copy h1 { margin:0; font-size:var(--text-title); font-weight:650; line-height:1.5; }
10
11
  .access-copy p { margin:0; color:var(--text-secondary); }
12
+ .access-form { display:flex; flex-direction:column; gap:10px; }
13
+ .access-field-row { display:flex; gap:8px; }
14
+ .access-input { flex:1; min-width:0; height:var(--field-height); padding:0 10px; border:1px solid var(--border); border-radius:var(--radius-field); background:var(--surface-sunken); color:var(--text); font:var(--text-meta)/1.2 var(--font-mono); }
15
+ .access-input::placeholder { color:var(--text-tertiary); opacity:1; }
16
+ .access-input:focus-visible { background:var(--surface); outline:1px solid var(--accent); outline-offset:-1px; }
17
+ .access-input[aria-invalid="true"] { border-color:var(--danger); }
18
+ .access-submit { flex:none; height:var(--field-height); padding:0 14px; border:0; border-radius:var(--radius-field); background:var(--accent); color:var(--on-accent); font:550 var(--text-body)/1 var(--font-ui); cursor:pointer; }
19
+ .access-submit:hover:not(:disabled) { filter:brightness(.94); }
20
+ .access-submit:focus-visible { outline:1px solid var(--accent); outline-offset:2px; }
21
+ .access-submit:disabled { opacity:.55; cursor:default; }
22
+ .access-error { margin:0; color:var(--danger); font-size:var(--text-meta); }
23
+ .access-hint { align-self:flex-start; padding:3px 8px; border-radius:var(--radius-keycap, 6px); background:var(--surface-sunken); color:var(--text-secondary); font:var(--text-caption)/1.4 var(--font-mono); user-select:all; }