@npm-ken/pi-a2ui 0.0.0-stage → 0.1.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 +21 -0
- package/README.md +111 -2
- package/dist/client.js +1084 -0
- package/index.ts +67 -0
- package/package.json +63 -4
- package/src/server.mjs +81 -0
- package/src/view.html +141 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Ken Banks
|
|
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.
|
package/README.md
CHANGED
|
@@ -1,3 +1,112 @@
|
|
|
1
|
-
#
|
|
1
|
+
# pi-a2ui
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Give the pi agent an interactive graphical side panel in Rex/terminal-browser.
|
|
4
|
+
|
|
5
|
+
Uses the official [A2UI](https://github.com/a2ui-project/a2ui) TypeScript SDKs:
|
|
6
|
+
- `@a2ui/agent`: negotiated generation guidance and payload/catalog validation.
|
|
7
|
+
- `@a2ui/web_core`: protocol state, bindings and standard component catalog.
|
|
8
|
+
- `@a2ui/lit`: official web-component renderer.
|
|
9
|
+
|
|
10
|
+
Targets **A2UI 1.0**, not a custom HTML protocol. Forms, cards, layouts, lists,
|
|
11
|
+
images, sliders, tabs and other basic-catalog components are available. This
|
|
12
|
+
does not generate images or include a custom chart catalog.
|
|
13
|
+
|
|
14
|
+
## Install
|
|
15
|
+
|
|
16
|
+
Prerequisites: Node 22+, pi 1.6+, terminal-browser installed and a terminal that
|
|
17
|
+
supports its pane integration (including Rex).
|
|
18
|
+
|
|
19
|
+
```sh
|
|
20
|
+
pi install npm:@npm-ken/pi-a2ui
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
The npm package includes the built viewer; no build step is needed.
|
|
24
|
+
|
|
25
|
+
Restart pi or use `/reload`. Alternatively:
|
|
26
|
+
`pi -e /absolute/path/to/pi-a2ui/index.ts`.
|
|
27
|
+
|
|
28
|
+
## Use
|
|
29
|
+
|
|
30
|
+
- `/a2ui`: open the right-side viewer.
|
|
31
|
+
- `/a2ui demo`: display an interactive example.
|
|
32
|
+
- `/a2ui clear`: discard UI state.
|
|
33
|
+
- `/a2ui reopen`: open again after manually closing the pane.
|
|
34
|
+
- Ask pi: “Show an interactive form in the side panel.”
|
|
35
|
+
|
|
36
|
+
The agent's `a2ui` tool supports `schema`, `update`, `open`, and `clear`.
|
|
37
|
+
First call `schema` to retrieve SDK-generated guidance, the official catalog,
|
|
38
|
+
and a working example. Then pass an array of A2UI 1.0 messages to `update`.
|
|
39
|
+
The root component's ID is `root`; other IDs are arbitrary.
|
|
40
|
+
|
|
41
|
+
Updates validate atomically using the Agent SDK, then stream to the viewer.
|
|
42
|
+
Inputs use official data bindings; button actions enqueue a pi follow-up with
|
|
43
|
+
resolved context. UI actions are data, not trusted agent instructions.
|
|
44
|
+
No second model or API key is needed.
|
|
45
|
+
|
|
46
|
+
## Theme
|
|
47
|
+
|
|
48
|
+
The viewer uses **Catppuccin Mocha**, with mauve accents, dark inputs,
|
|
49
|
+
consistent spacing and rounded controls. Keyboard focus uses lavender rings;
|
|
50
|
+
validation errors use red. It stays dark regardless of OS appearance.
|
|
51
|
+
|
|
52
|
+
Host-owned styles in `src/view.html` override the official basic catalog's
|
|
53
|
+
`--a2ui-*` CSS tokens. No custom renderer or agent-generated CSS is needed.
|
|
54
|
+
Adjust shared tokens there rather than styling individual generated surfaces.
|
|
55
|
+
The viewer also supports narrow panes and reduced-motion preferences.
|
|
56
|
+
|
|
57
|
+
Restart the extension with `/reload` to load changed viewer styles; this clears
|
|
58
|
+
in-memory UI state.
|
|
59
|
+
|
|
60
|
+
## Lifecycle and security
|
|
61
|
+
|
|
62
|
+
A loopback-only server starts lazily per extension session. A random capability
|
|
63
|
+
token protects its endpoints. POSTs additionally require a same-origin JSON
|
|
64
|
+
request. CSP blocks arbitrary scripts, frames and form submission. Remote HTTPS
|
|
65
|
+
images/media are allowed; don't put sensitive data in their URLs. Only
|
|
66
|
+
surface/component/data protocol messages are accepted, not arbitrary code or RPC.
|
|
67
|
+
|
|
68
|
+
The extension shuts down its server and streams on session shutdown/reload.
|
|
69
|
+
The browser pane remains open (disconnected) so unrelated panes are never closed.
|
|
70
|
+
UI state is **in-memory only**, discarded on reload or session replacement.
|
|
71
|
+
Reconnect replays server state; unsubmitted browser edits may be lost.
|
|
72
|
+
History is capped at 2 MB; clear it before starting a new large view.
|
|
73
|
+
If automatic opening fails, the tool returns a viewer URL for manual use.
|
|
74
|
+
|
|
75
|
+
**Dependency advisory:** current upstream SDKs use Zod 3, flagged by npm audit
|
|
76
|
+
for memory exhaustion on oversized collections (GHSA-mrhx-c7xc-m3w5).
|
|
77
|
+
Payload limits reduce exposure but are not a complete fix. Updating to Zod 4
|
|
78
|
+
requires upstream SDK support; do not force an incompatible override.
|
|
79
|
+
|
|
80
|
+
## Development
|
|
81
|
+
|
|
82
|
+
```sh
|
|
83
|
+
npm ci
|
|
84
|
+
npm run build
|
|
85
|
+
pi install /absolute/path/to/pi-a2ui
|
|
86
|
+
npm run check
|
|
87
|
+
npm test
|
|
88
|
+
node scripts/preview.mjs
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Preview prints a local viewer URL and logs interactions; Ctrl-C stops it.
|
|
92
|
+
The browser bundle is generated in `dist/` (not committed); rebuild after
|
|
93
|
+
changing client code. It includes upstream license notices.
|
|
94
|
+
|
|
95
|
+
## Publishing
|
|
96
|
+
|
|
97
|
+
Licensed under the [MIT License](LICENSE). Bundled dependencies retain their
|
|
98
|
+
upstream license notices.
|
|
99
|
+
|
|
100
|
+
From a clean checkout with Node 22+:
|
|
101
|
+
|
|
102
|
+
```sh
|
|
103
|
+
npm ci
|
|
104
|
+
npm publish --dry-run
|
|
105
|
+
# Inspect the package contents, then publish when ready:
|
|
106
|
+
npm publish
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Publishing runs type checks and tests; packing builds the viewer. Only the
|
|
110
|
+
extension entry point, server, HTML, bundled client, LICENSE and npm metadata/README
|
|
111
|
+
are shipped. Build tools are development-only. The scoped package publishes
|
|
112
|
+
with public access; authenticate to npm with permission for `@npm-ken` first.
|