@whzxc/agent-design-gallery 0.0.0-stage → 0.6.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.
- package/LICENSE +69 -0
- package/README.md +216 -2
- package/package.json +43 -4
- package/public/access.css +10 -0
- package/public/app.js +1646 -0
- package/public/assets.js +344 -0
- package/public/auth.js +69 -0
- package/public/favicon.svg +6 -0
- package/public/hub.css +67 -0
- package/public/hub.html +33 -0
- package/public/hub.js +165 -0
- package/public/icons.js +50 -0
- package/public/index.html +70 -0
- package/public/instance-actions.js +27 -0
- package/public/labels.js +122 -0
- package/public/layout.js +103 -0
- package/public/relationships.js +28 -0
- package/public/selection.js +20 -0
- package/public/style.css +194 -0
- package/public/switcher.css +37 -0
- package/public/switcher.js +176 -0
- package/public/token-catalog.js +129 -0
- package/public/tokens.css +61 -0
- package/public/view-route.js +66 -0
- package/src/cli.mjs +105 -0
- package/src/http.mjs +37 -0
- package/src/hub/auth.mjs +40 -0
- package/src/hub/instances.mjs +99 -0
- package/src/hub/proxy.mjs +28 -0
- package/src/hub/registry.mjs +147 -0
- package/src/hub.mjs +113 -0
- package/src/link.mjs +54 -0
- package/src/open.mjs +57 -0
- package/src/server.mjs +642 -0
- package/src/service.mjs +163 -0
- package/src/toolkit/arch-browser.mjs +40 -0
- package/src/toolkit/arch-git.mjs +54 -0
- package/src/toolkit/arch-overlay.mjs +225 -0
- package/src/toolkit/arch.mjs +217 -0
- package/src/toolkit/asset-rules.mjs +14 -0
- package/src/toolkit/browser.mjs +21 -0
- package/src/toolkit/build-store.mjs +258 -0
- package/src/toolkit/build-worker.mjs +32 -0
- package/src/toolkit/build.mjs +133 -0
- package/src/toolkit/commands.mjs +273 -0
- package/src/toolkit/compare.mjs +175 -0
- package/src/toolkit/config.mjs +135 -0
- package/src/toolkit/document.mjs +85 -0
- package/src/toolkit/migrate.mjs +73 -0
- package/src/toolkit/project.mjs +160 -0
- package/src/toolkit/runtime.d.ts +14 -0
- package/src/toolkit/runtime.mjs +54 -0
- package/src/toolkit/text.mjs +12 -0
- package/src/toolkit/tokens.mjs +36 -0
- package/src/viewer-cache.mjs +85 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 whzxc
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
Lucide icon geometry
|
|
26
|
+
|
|
27
|
+
ISC License
|
|
28
|
+
|
|
29
|
+
Copyright (c) 2026 Lucide Icons and Contributors
|
|
30
|
+
|
|
31
|
+
Permission to use, copy, modify, and/or distribute this software for any
|
|
32
|
+
purpose with or without fee is hereby granted, provided that the above
|
|
33
|
+
copyright notice and this permission notice appear in all copies.
|
|
34
|
+
|
|
35
|
+
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
36
|
+
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
37
|
+
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
38
|
+
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
39
|
+
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
40
|
+
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
41
|
+
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
The following Lucide icons are derived from the Feather project:
|
|
46
|
+
|
|
47
|
+
airplay, alert-circle, alert-octagon, alert-triangle, aperture, arrow-down-circle, arrow-down-left, arrow-down-right, arrow-down, arrow-left-circle, arrow-left, arrow-right-circle, arrow-right, arrow-up-circle, arrow-up-left, arrow-up-right, arrow-up, at-sign, calendar, cast, check, chevron-down, chevron-left, chevron-right, chevron-up, chevrons-down, chevrons-left, chevrons-right, chevrons-up, circle, clipboard, clock, code, columns, command, compass, corner-down-left, corner-down-right, corner-left-down, corner-left-up, corner-right-down, corner-right-up, corner-up-left, corner-up-right, crosshair, database, divide-circle, divide-square, dollar-sign, download, external-link, feather, frown, hash, headphones, help-circle, info, italic, key, layout, life-buoy, link-2, link, loader, lock, log-in, log-out, maximize, meh, minimize, minimize-2, minus-circle, minus-square, minus, monitor, moon, more-horizontal, more-vertical, move, music, navigation-2, navigation, octagon, pause-circle, percent, plus-circle, plus-square, plus, power, radio, rss, search, server, share, shopping-bag, sidebar, smartphone, smile, square, table-2, tablet, target, terminal, trash-2, trash, triangle, tv, type, upload, x-circle, x-octagon, x-square, x, zoom-in, zoom-out
|
|
48
|
+
|
|
49
|
+
The MIT License (MIT) (for the icons listed above)
|
|
50
|
+
|
|
51
|
+
Copyright (c) 2013-present Cole Bemis
|
|
52
|
+
|
|
53
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
54
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
55
|
+
in the Software without restriction, including without limitation the rights
|
|
56
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
57
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
58
|
+
furnished to do so, subject to the following conditions:
|
|
59
|
+
|
|
60
|
+
The above copyright notice and this permission notice shall be included in all
|
|
61
|
+
copies or substantial portions of the Software.
|
|
62
|
+
|
|
63
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
64
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
65
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
66
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
67
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
68
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
69
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,217 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Agent Design Gallery
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Build and browse a repository's TSX design frames with a local browser canvas.
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
npm install -g @whzxc/agent-design-gallery
|
|
7
|
+
adg /path/to/design
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
Requires Node.js 22 or newer. Installation starts without a build step. TSX builds never load Chromium. Architecture builds use the bundled Playwright dependency to measure labels in Chromium, including in the viewer and hub. Each build worker starts one browser lazily, reuses it, and closes it after 30 seconds idle or on worker retirement. Browser toolkit commands also use Chromium; `check` and `render` share their existing browser with architecture measurement.
|
|
11
|
+
|
|
12
|
+
`adg` opens a loopback server in your default browser. Use `--no-open` to print its URL, `--port 5200` to select a port, or omit the directory to use the current project. Stop the server with Ctrl+C.
|
|
13
|
+
|
|
14
|
+
## Migrate an existing installation
|
|
15
|
+
|
|
16
|
+
Install the new package, then run these one-time commands:
|
|
17
|
+
|
|
18
|
+
```sh
|
|
19
|
+
adg migrate /path/to/project
|
|
20
|
+
adg service migrate
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
`adg migrate [project]` defaults to the current directory. It renames `sdg.config.mjs`, `.js` or `.ts` to
|
|
24
|
+
`adg.config.*`, rewrites design-source imports from `sdg` (including runtime subpaths and `sdg:self`) to `adg`,
|
|
25
|
+
updates design editor paths and `.sdg/` entries in the project's `.gitignore` files, deletes the old generated
|
|
26
|
+
`design/.sdg/` directory and regenerates `design/.adg/` (using the configured design directory). It prints each
|
|
27
|
+
change and is safe to repeat. When both config names exist, it refuses before changing files. Normal commands
|
|
28
|
+
finding only an old config stop with guidance to run `adg migrate`.
|
|
29
|
+
|
|
30
|
+
On macOS, `adg service migrate` stops `org.svg-design-gallery.hub`, moves its entire state directory from
|
|
31
|
+
`svg-design-gallery` to `agent-design-gallery`, and replaces the LaunchAgent with `org.agent-design-gallery.hub`
|
|
32
|
+
using the current Node and CLI paths and the previous port. It resolves the source from the old LaunchAgent's
|
|
33
|
+
`--state-dir`, or `$XDG_STATE_HOME/svg-design-gallery` (default `~/.local/state/svg-design-gallery`). The destination
|
|
34
|
+
is `$XDG_STATE_HOME/agent-design-gallery` by default; `--state-dir` selects a different destination. It refuses an
|
|
35
|
+
existing target directory or new LaunchAgent. It prints steps and then lists other LaunchAgents still referencing
|
|
36
|
+
the old state path without editing them or printing keys. Registry, preferences, caches and logs move together.
|
|
37
|
+
The stored key prefix changes to `adg_`; update browser access with the new key through `adg serve --print-key`.
|
|
38
|
+
|
|
39
|
+
## Viewer controls
|
|
40
|
+
|
|
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
|
+
|
|
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.
|
|
44
|
+
|
|
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
|
+
|
|
47
|
+
## Share a design update
|
|
48
|
+
|
|
49
|
+
```sh
|
|
50
|
+
adg link https://gallery.example/p/project/ --asset=components/button.tsx --frame=disabled
|
|
51
|
+
adg link https://gallery.example/p/project/ --asset=components/button.tsx --frame=disabled --mode=path
|
|
52
|
+
adg open ./design --asset=components/button.tsx --frame=disabled --no-open
|
|
53
|
+
adg render components/button --frame=disabled --theme=dark --out-dir=output/review --json
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Use the independent link in a change report. Add the path link when the surrounding assets matter. Use the project URL on a hub the recipient can reach. `adg open` provides a live loopback preview while its server runs. `render` exports exact frame PNGs for attachments or automation. Without `--theme`, it exports both themes. See the [review handoff workflow](docs/design-toolkit.md#review-handoff).
|
|
57
|
+
|
|
58
|
+
The rightmost toolbar button opens the Inspector for the selected node. It starts closed and overlays the canvas. It follows the selection and shows source path, frame name, dimensions, frames, and discovered **Uses** / **Used by** relationships. Indirect relationships are muted with their shortest `via` path. Click a relationship to focus the source, or to open it by itself when outside the current scope. An element selection shows its owning export and matching frames from the current scope. `GET /relationships` explicitly computes the complete direct graph as JSON, keyed by source path with `uses` and `usedBy` arrays.
|
|
59
|
+
|
|
60
|
+
Click a canvas source or frame title to select it and copy its name. The copy icon copies without changing the selection and appears on hover or keyboard focus. Section titles also copy their names. Enter and Space activate a focused title. A check confirms a successful copy for 1.2 seconds. The inspector has separate source-path and frame-name copy controls.
|
|
61
|
+
|
|
62
|
+
**More** opens Fullscreen, System/Light/Dark theme choices, canvas background choices, **Arrange current group**, and **Keyboard shortcuts** (also available with ?).
|
|
63
|
+
|
|
64
|
+
The bottom zoom bar holds Back, zoom out, the zoom menu, zoom in, Fit, and Minimap. The zoom menu offers Fit all, Fit group, Fit selection, and Zoom to 100%. Fit uses the selected frame or element, source, or current group. The minimap moves the camera when clicked. The inspector lists forms or frames with their geometric sizes and notes.
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
## Sources and layout
|
|
69
|
+
|
|
70
|
+
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`.
|
|
71
|
+
|
|
72
|
+
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.
|
|
73
|
+
|
|
74
|
+
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, review batches, 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.
|
|
75
|
+
|
|
76
|
+
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.
|
|
77
|
+
|
|
78
|
+
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.
|
|
79
|
+
|
|
80
|
+
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.
|
|
81
|
+
|
|
82
|
+
Files group by directory unless `gallery.json` supplies project groups. Entries must point directly into configured source directories:
|
|
83
|
+
|
|
84
|
+
```json
|
|
85
|
+
{
|
|
86
|
+
"groups": [
|
|
87
|
+
{ "title": "Controls", "assets": ["components/button.tsx", "components/field.tsx"] },
|
|
88
|
+
{ "title": "Settings", "assets": ["surfaces/settings.tsx"] }
|
|
89
|
+
]
|
|
90
|
+
}
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
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 `$XDG_STATE_HOME/agent-design-gallery/state.json`, defaulting to `~/.local/state/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.
|
|
94
|
+
|
|
95
|
+
## Design toolkit
|
|
96
|
+
|
|
97
|
+
Run commands from inside the project:
|
|
98
|
+
|
|
99
|
+
```sh
|
|
100
|
+
adg init
|
|
101
|
+
adg check
|
|
102
|
+
adg render surfaces/example --frame=default --scale=2
|
|
103
|
+
adg check --read-only
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
`init` creates tokens, components/modules/surfaces, fixtures/art, editor configuration and ignore entries. A fresh library gets one `example.tsx` per production layer, composed downward with shared fixture data; existing libraries receive no demo sources. Existing authored files are preserved, declarations are refreshed, and missing ignore entries are appended. Starter configuration requires ADG 0.5.0 or newer. `check --read-only` skips declarations and build files for an audit. Projects do not install ADG as a dependency.
|
|
107
|
+
|
|
108
|
+
Builds produce standalone HTML and renders produce `<frame>-light.png` and `<frame>-dark.png` under `output/design/<source>/`. After configuring an implementation adapter and frame fixture/capture, use `adg compare <source> --frame=<name>` or `adg compare --all`. Flags override Frame capture props; `--all` writes a linked HTML index and `summary.json` under `output/design/compare/`. `sync` and `measure` have been removed.
|
|
109
|
+
|
|
110
|
+
See the [toolkit contract](docs/design-toolkit.md) for source format and compare adapters, and the [changelog](CHANGELOG.md) for version changes. Node.js executes design modules at build time; open sources you trust.
|
|
111
|
+
|
|
112
|
+
## Architecture sources
|
|
113
|
+
|
|
114
|
+
ADG discovers Mermaid `.mmd` files recursively under the project-root `arch/` directory.
|
|
115
|
+
They appear in the Arch scope alongside UI sources, with one `default` frame per diagram.
|
|
116
|
+
Set `arch: 'architecture'` or `arch: false` in the project config to change discovery.
|
|
117
|
+
Project tokens paint both themes; an optional adjacent `.md` supplies Inspector notes,
|
|
118
|
+
code owners and status. Pele is pinned to 1.12.0.
|
|
119
|
+
|
|
120
|
+
```sh
|
|
121
|
+
adg open . --asset=arch/system-map.mmd
|
|
122
|
+
adg check arch/system-map.mmd --read-only
|
|
123
|
+
adg render arch/system-map.mmd --theme=both --json
|
|
124
|
+
adg open . --asset=arch/system-map.mmd --base=HEAD
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
See [architecture source format](docs/design-toolkit.md#architecture-sources) for the
|
|
128
|
+
semantic vocabulary, sidecar grammar and checks.
|
|
129
|
+
|
|
130
|
+
## Development
|
|
131
|
+
|
|
132
|
+
```sh
|
|
133
|
+
npm ci
|
|
134
|
+
npm start -- /path/to/design --no-open
|
|
135
|
+
npm test
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
The development server serves the checked-in frontend and `design/tokens.css` directly. A globally installed server serves its installed package; repository edits and Git commits do not update that installation. Reload after static frontend edits. Restart after server/toolkit edits or changes to `public/assets.js`, `public/layout.js` or `public/selection.js`, whose combined hash identifies the viewer cache context. `npm pack` copies the shared viewer tokens into the packaged browser files. No frontend framework is required.
|
|
139
|
+
|
|
140
|
+
After a completed runtime or dependency milestone passes its relevant checks and required design approvals, maintainers update the global installation and verify the deployed viewer as part of delivery. Follow [local updates](docs/local-updates.md) for packing, installation, restart conditions and endpoint verification. Documentation-only, test-only and fixture-only commits skip this update.
|
|
141
|
+
|
|
142
|
+
Maintainers publish releases to the public npm registry; a scope registry in the local npm config takes precedence over `publishConfig`, so override it with `npm publish --@whzxc:registry=https://registry.npmjs.org/`. Local milestone updates can install a tarball without publishing or changing the package version.
|
|
143
|
+
|
|
144
|
+
See [ADG design](docs/design.md), [architecture](docs/architecture.md), and [performance](docs/performance.md). ARC's MIT-licensed gallery is the starting point; the MIT license and Lucide/Feather icon notices are retained in `LICENSE`.
|
|
145
|
+
|
|
146
|
+
## Resident hub
|
|
147
|
+
|
|
148
|
+
`adg open <dir>` stays independent: no registry or hub is required, and the port is random by default. It accepts a design directory or a configured project root. The browser is read-only apart from viewer preferences. Select directories from the CLI; the browser has no reveal action.
|
|
149
|
+
|
|
150
|
+
```sh
|
|
151
|
+
adg root add ~/Developer --depth 2
|
|
152
|
+
adg root list
|
|
153
|
+
adg root scan # Explicit rescan of registered roots
|
|
154
|
+
adg root scan ~/Developer
|
|
155
|
+
adg root remove ~/Developer
|
|
156
|
+
adg serve --port 4310
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
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.
|
|
160
|
+
|
|
161
|
+
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.
|
|
162
|
+
|
|
163
|
+
### Access keys and instances
|
|
164
|
+
|
|
165
|
+
The hub creates `hub.key` in its state directory on first start with mode 0600. Direct-local data requests are exempt: Host must be localhost, 127.0.0.1 or ::1, with no Forwarded or X-Forwarded-* header present. The peer IP is never used for this decision.
|
|
166
|
+
|
|
167
|
+
```sh
|
|
168
|
+
adg serve --print-key # Print the current key and exit
|
|
169
|
+
adg serve --rotate-key # Replace the key and exit
|
|
170
|
+
adg serve --rotate-key --print-key # Replace and print it
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
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.
|
|
174
|
+
|
|
175
|
+
`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.
|
|
176
|
+
|
|
177
|
+
Close a verified live instance from its row on the hub home or in the project switcher. Closing the current viewer returns to the hub home. The switcher shows the instance's port to distinguish viewers with the same name. `POST /api/instances/<id>/stop` rechecks the registered instance before asking its process to shut down.
|
|
178
|
+
|
|
179
|
+
`/i/<id>/` streams from that instance's own server, including its viewer runtime and SSE. The hub serves the project switcher and its instance controls for both prefixed routes. Public shell requests pass through without data; every proxied data request is authenticated before forwarding, then Authorization, X-ADG-Key, query key, cookies and forwarded headers are removed upstream. Relative viewer URLs preserve `/p/<slug>/` and `/i/<id>/`. Browser writes through either prefix are limited to viewer preferences and derived cache data.
|
|
180
|
+
|
|
181
|
+
### nginx
|
|
182
|
+
|
|
183
|
+
Keep the listener on loopback and terminate remote HTTPS at nginx. Preserve the original Host, the full URI prefixes and all query parameters. nginx must set forwarded headers on **every** request, including requests whose original Host is localhost: this prevents the direct-local exemption through a local proxy. Supply the following in a root location:
|
|
184
|
+
|
|
185
|
+
```nginx
|
|
186
|
+
location / {
|
|
187
|
+
proxy_pass http://127.0.0.1:4310;
|
|
188
|
+
proxy_http_version 1.1;
|
|
189
|
+
proxy_set_header Host $http_host;
|
|
190
|
+
proxy_set_header X-Forwarded-Host $http_host;
|
|
191
|
+
proxy_set_header X-Forwarded-Proto $scheme;
|
|
192
|
+
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|
193
|
+
proxy_set_header Forwarded "";
|
|
194
|
+
proxy_set_header Authorization $http_authorization;
|
|
195
|
+
proxy_set_header X-ADG-Key $http_x_adg_key;
|
|
196
|
+
proxy_set_header Connection "";
|
|
197
|
+
proxy_buffering off;
|
|
198
|
+
proxy_cache off;
|
|
199
|
+
proxy_read_timeout 1h;
|
|
200
|
+
}
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
The proxy_pass has no URI suffix; do not strip `/p/<slug>/` or `/i/<id>/`. Disable SSE buffering and caching. Avoid logging query strings or key headers: the initial URL and SSE carry the key. Cookies are not used.
|
|
204
|
+
|
|
205
|
+
|
|
206
|
+
### macOS resident service
|
|
207
|
+
|
|
208
|
+
```sh
|
|
209
|
+
adg service install [--port 4310] [--state-dir /absolute/state/path]
|
|
210
|
+
adg service status
|
|
211
|
+
adg service logs
|
|
212
|
+
adg service uninstall
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
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.
|
|
216
|
+
|
|
217
|
+
`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.
|
package/package.json
CHANGED
|
@@ -1,6 +1,45 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@whzxc/agent-design-gallery",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.6.0",
|
|
4
|
+
"description": "Local TSX design toolkit and SVG viewer",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"license": "MIT",
|
|
7
|
+
"bin": {
|
|
8
|
+
"adg": "src/cli.mjs"
|
|
9
|
+
},
|
|
10
|
+
"engines": {
|
|
11
|
+
"node": ">=22"
|
|
12
|
+
},
|
|
13
|
+
"files": [
|
|
14
|
+
"src",
|
|
15
|
+
"public",
|
|
16
|
+
"LICENSE",
|
|
17
|
+
"README.md"
|
|
18
|
+
],
|
|
19
|
+
"repository": {
|
|
20
|
+
"type": "git",
|
|
21
|
+
"url": "git+https://github.com/whzxc/agent-design-gallery.git"
|
|
22
|
+
},
|
|
23
|
+
"publishConfig": {
|
|
24
|
+
"registry": "https://registry.npmjs.org/",
|
|
25
|
+
"access": "public"
|
|
26
|
+
},
|
|
27
|
+
"scripts": {
|
|
28
|
+
"start": "node src/cli.mjs",
|
|
29
|
+
"benchmark": "node tooling/benchmark.mjs",
|
|
30
|
+
"compare": "node tooling/compare.mjs",
|
|
31
|
+
"test": "node --test test/*.test.mjs",
|
|
32
|
+
"prepack": "node tooling/package.mjs"
|
|
33
|
+
},
|
|
34
|
+
"dependencies": {
|
|
35
|
+
"esbuild": "0.28.2",
|
|
36
|
+
"lucide": "1.70.0",
|
|
37
|
+
"pele": "1.12.0",
|
|
38
|
+
"playwright": "1.64.1",
|
|
39
|
+
"tailwindcss": "4.3.4"
|
|
40
|
+
},
|
|
41
|
+
"homepage": "https://github.com/whzxc/agent-design-gallery#readme",
|
|
42
|
+
"bugs": {
|
|
43
|
+
"url": "https://github.com/whzxc/agent-design-gallery/issues"
|
|
44
|
+
}
|
|
45
|
+
}
|
|
@@ -0,0 +1,10 @@
|
|
|
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; }
|
|
2
|
+
.access-shell * { box-sizing:border-box; }
|
|
3
|
+
.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
|
+
.access-center { display:flex; flex:1; align-items:center; justify-content:center; }
|
|
5
|
+
.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
|
+
.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-copy { display:flex; flex-direction:column; gap:8px; }
|
|
9
|
+
.access-copy h1 { margin:0; font-size:var(--text-title); font-weight:650; line-height:1.5; }
|
|
10
|
+
.access-copy p { margin:0; color:var(--text-secondary); }
|