@puredesktop/create-app 2.1.5 → 2.1.7
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/bin/create-puredesktop-app.mjs +319 -319
- package/package.json +1 -1
- package/template/README.md +52 -52
- package/template/agents.md +11 -11
- package/template/docs/README.md +30 -30
- package/template/docs/agent.md +58 -58
- package/template/docs/app-lifecycle.md +60 -60
- package/template/docs/bridge/README.md +84 -84
- package/template/docs/bridge/dialog.md +56 -56
- package/template/docs/bridge/fs.md +95 -95
- package/template/docs/bridge/network.md +38 -38
- package/template/docs/bridge/settings.md +63 -63
- package/template/docs/bridge/storage.md +48 -48
- package/template/docs/plugin-manifest.md +104 -104
- package/template/docs/theme-vars.md +79 -79
- package/template/docs/tool-handlers.md +122 -122
- package/template/docs/ui-and-components.md +57 -56
- package/template/package.json +10 -10
- package/template/plugin.json +20 -20
- package/template/src/App.tsx +4 -4
- package/template/src/bridge/platformBridge.ts +122 -122
- package/template/src/components/AppShell.tsx +9 -9
|
@@ -1,108 +1,108 @@
|
|
|
1
|
-
# Plugin Manifest
|
|
2
|
-
|
|
3
|
-
`plugin.json` is the shell contract for discovery, permissions, routing, and app
|
|
4
|
-
agent tools.
|
|
5
|
-
|
|
6
|
-
## Required Shape
|
|
7
|
-
|
|
8
|
-
```json
|
|
9
|
-
{
|
|
10
|
-
"schemaVersion": 1,
|
|
11
|
-
"id": "{{PLUGIN_ID}}",
|
|
12
|
-
"name": "{{APP_TITLE}}",
|
|
13
|
-
"permissions": ["network", "settings", "agents"],
|
|
14
|
-
"entrypoint": {
|
|
15
|
-
"kind": "dev-url",
|
|
16
|
-
"url": "http://localhost:{{APP_PORT}}"
|
|
17
|
-
},
|
|
18
|
-
"app": {
|
|
19
|
-
"id": "plugin.{{APP_SLUG}}",
|
|
20
|
-
"slug": "{{APP_SLUG}}",
|
|
21
|
-
"name": "{{APP_TITLE}}",
|
|
22
|
-
"navigationLabel": "{{APP_TITLE}}",
|
|
23
|
-
"productName": "pure.{{APP_SLUG}}",
|
|
24
|
-
"kind": "{{APP_SLUG}}",
|
|
25
|
-
"description": "{{APP_TITLE}} - built with PureDesktop.",
|
|
26
|
-
"usePureDesktopAiPanel": true
|
|
27
|
-
}
|
|
28
|
-
}
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
`app.slug` is the API scope for settings, storage, app agent sessions, and tab
|
|
32
|
-
routing. `src/constants.ts` `APP_SLUG` must match `plugin.json` `app.slug`.
|
|
33
|
-
|
|
34
|
-
## Entrypoint
|
|
35
|
-
|
|
36
|
-
Development apps use:
|
|
37
|
-
|
|
38
|
-
```json
|
|
39
|
-
{
|
|
40
|
-
"entrypoint": {
|
|
41
|
-
"kind": "dev-url",
|
|
42
|
-
"url": "http://localhost:{{APP_PORT}}"
|
|
43
|
-
}
|
|
44
|
-
}
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
Built apps use a static bundle registered from `dist/`. The validator checks the
|
|
48
|
-
build output before registration.
|
|
49
|
-
|
|
50
|
-
## Permissions
|
|
51
|
-
|
|
52
|
-
Declare every shell capability used by bridge helpers:
|
|
53
|
-
|
|
54
|
-
| Permission | Enables |
|
|
55
|
-
| --- | --- |
|
|
56
|
-
| `settings` | `settings.*`, app settings, user preferences |
|
|
57
|
-
| `filesystem` | `fs.*`, `dialog.*`, `storage.*`, file open routing |
|
|
58
|
-
| `network` | `network.fetch`, hosted entrypoints, OAuth helpers |
|
|
59
|
-
| `render` | document render and print helpers |
|
|
60
|
-
| `assets` | asset library helpers |
|
|
61
|
-
| `agents` | app agent sessions and runtime tool handlers |
|
|
62
|
-
|
|
63
|
-
## App Agent Tools
|
|
64
|
-
|
|
65
|
-
Declare app-owned tools under `app.agents.tools`:
|
|
66
|
-
|
|
67
|
-
```json
|
|
68
|
-
{
|
|
69
|
-
"app": {
|
|
70
|
-
"agents": {
|
|
71
|
-
"tools": [
|
|
72
|
-
{
|
|
73
|
-
"name": "listItems",
|
|
74
|
-
"description": "List the current items with ids, titles, status, and next action.",
|
|
75
|
-
"inputSchema": {
|
|
76
|
-
"type": "object",
|
|
77
|
-
"properties": {
|
|
78
|
-
"status": {
|
|
79
|
-
"type": "string",
|
|
80
|
-
"description": "Optional status filter."
|
|
81
|
-
}
|
|
82
|
-
},
|
|
83
|
-
"additionalProperties": false
|
|
84
|
-
},
|
|
85
|
-
"requiresApproval": false
|
|
86
|
-
}
|
|
87
|
-
]
|
|
88
|
-
}
|
|
89
|
-
}
|
|
90
|
-
}
|
|
91
|
-
```
|
|
92
|
-
|
|
93
|
-
The manifest declaration exposes the tool to the shell agent. Runtime handler
|
|
94
|
-
registration in the iframe executes the tool.
|
|
95
|
-
|
|
96
|
-
## Validation
|
|
97
|
-
|
|
98
|
-
Run:
|
|
99
|
-
|
|
100
|
-
```bash
|
|
1
|
+
# Plugin Manifest
|
|
2
|
+
|
|
3
|
+
`plugin.json` is the shell contract for discovery, permissions, routing, and app
|
|
4
|
+
agent tools.
|
|
5
|
+
|
|
6
|
+
## Required Shape
|
|
7
|
+
|
|
8
|
+
```json
|
|
9
|
+
{
|
|
10
|
+
"schemaVersion": 1,
|
|
11
|
+
"id": "{{PLUGIN_ID}}",
|
|
12
|
+
"name": "{{APP_TITLE}}",
|
|
13
|
+
"permissions": ["network", "settings", "agents"],
|
|
14
|
+
"entrypoint": {
|
|
15
|
+
"kind": "dev-url",
|
|
16
|
+
"url": "http://localhost:{{APP_PORT}}"
|
|
17
|
+
},
|
|
18
|
+
"app": {
|
|
19
|
+
"id": "plugin.{{APP_SLUG}}",
|
|
20
|
+
"slug": "{{APP_SLUG}}",
|
|
21
|
+
"name": "{{APP_TITLE}}",
|
|
22
|
+
"navigationLabel": "{{APP_TITLE}}",
|
|
23
|
+
"productName": "pure.{{APP_SLUG}}",
|
|
24
|
+
"kind": "{{APP_SLUG}}",
|
|
25
|
+
"description": "{{APP_TITLE}} - built with PureDesktop.",
|
|
26
|
+
"usePureDesktopAiPanel": true
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
`app.slug` is the API scope for settings, storage, app agent sessions, and tab
|
|
32
|
+
routing. `src/constants.ts` `APP_SLUG` must match `plugin.json` `app.slug`.
|
|
33
|
+
|
|
34
|
+
## Entrypoint
|
|
35
|
+
|
|
36
|
+
Development apps use:
|
|
37
|
+
|
|
38
|
+
```json
|
|
39
|
+
{
|
|
40
|
+
"entrypoint": {
|
|
41
|
+
"kind": "dev-url",
|
|
42
|
+
"url": "http://localhost:{{APP_PORT}}"
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Built apps use a static bundle registered from `dist/`. The validator checks the
|
|
48
|
+
build output before registration.
|
|
49
|
+
|
|
50
|
+
## Permissions
|
|
51
|
+
|
|
52
|
+
Declare every shell capability used by bridge helpers:
|
|
53
|
+
|
|
54
|
+
| Permission | Enables |
|
|
55
|
+
| --- | --- |
|
|
56
|
+
| `settings` | `settings.*`, app settings, user preferences |
|
|
57
|
+
| `filesystem` | `fs.*`, `dialog.*`, `storage.*`, file open routing |
|
|
58
|
+
| `network` | `network.fetch`, hosted entrypoints, OAuth helpers |
|
|
59
|
+
| `render` | document render and print helpers |
|
|
60
|
+
| `assets` | asset library helpers |
|
|
61
|
+
| `agents` | app agent sessions and runtime tool handlers |
|
|
62
|
+
|
|
63
|
+
## App Agent Tools
|
|
64
|
+
|
|
65
|
+
Declare app-owned tools under `app.agents.tools`:
|
|
66
|
+
|
|
67
|
+
```json
|
|
68
|
+
{
|
|
69
|
+
"app": {
|
|
70
|
+
"agents": {
|
|
71
|
+
"tools": [
|
|
72
|
+
{
|
|
73
|
+
"name": "listItems",
|
|
74
|
+
"description": "List the current items with ids, titles, status, and next action.",
|
|
75
|
+
"inputSchema": {
|
|
76
|
+
"type": "object",
|
|
77
|
+
"properties": {
|
|
78
|
+
"status": {
|
|
79
|
+
"type": "string",
|
|
80
|
+
"description": "Optional status filter."
|
|
81
|
+
}
|
|
82
|
+
},
|
|
83
|
+
"additionalProperties": false
|
|
84
|
+
},
|
|
85
|
+
"requiresApproval": false
|
|
86
|
+
}
|
|
87
|
+
]
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
The manifest declaration exposes the tool to the shell agent. Runtime handler
|
|
94
|
+
registration in the iframe executes the tool.
|
|
95
|
+
|
|
96
|
+
## Validation
|
|
97
|
+
|
|
98
|
+
Run:
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
101
|
npm run typecheck
|
|
102
|
-
npm run build
|
|
103
|
-
npm run puredesktop:check
|
|
104
|
-
```
|
|
105
|
-
|
|
102
|
+
npm run build
|
|
103
|
+
npm run puredesktop:check
|
|
104
|
+
```
|
|
105
|
+
|
|
106
106
|
The validator checks manifest identity, required scripts and dependencies,
|
|
107
107
|
`agents.md`, `app.usePureDesktopAiPanel`, permissions, built output, and declared
|
|
108
108
|
agent tool presence in source and dist.
|
|
@@ -9,85 +9,85 @@ spacing, typography, radii, shadows, transitions, or app stacking values.
|
|
|
9
9
|
This static reference is generated by PureDesktop maintainers before the
|
|
10
10
|
create-app package is released.
|
|
11
11
|
|
|
12
|
-
| Variable | Domain |
|
|
13
|
-
| --- | --- |
|
|
14
|
-
| `--platform-colors-accent` | colors |
|
|
15
|
-
| `--platform-colors-accent-hover` | colors |
|
|
16
|
-
| `--platform-colors-accent-muted` | colors |
|
|
17
|
-
| `--platform-colors-app-viewport` | colors |
|
|
18
|
-
| `--platform-colors-bg` | colors |
|
|
19
|
-
| `--platform-colors-border` | colors |
|
|
20
|
-
| `--platform-colors-border-strong` | colors |
|
|
21
|
-
| `--platform-colors-chrome-tab-strip` | colors |
|
|
22
|
-
| `--platform-colors-chrome-titlebar` | colors |
|
|
23
|
-
| `--platform-colors-danger` | colors |
|
|
24
|
-
| `--platform-colors-divider` | colors |
|
|
25
|
-
| `--platform-colors-elevated` | colors |
|
|
26
|
-
| `--platform-colors-focus` | colors |
|
|
27
|
-
| `--platform-colors-info` | colors |
|
|
28
|
-
| `--platform-colors-selection` | colors |
|
|
29
|
-
| `--platform-colors-semantic-blue` | colors |
|
|
30
|
-
| `--platform-colors-semantic-blue-border` | colors |
|
|
31
|
-
| `--platform-colors-semantic-blue-muted` | colors |
|
|
32
|
-
| `--platform-colors-semantic-blue-text` | colors |
|
|
33
|
-
| `--platform-colors-semantic-green` | colors |
|
|
34
|
-
| `--platform-colors-semantic-green-border` | colors |
|
|
35
|
-
| `--platform-colors-semantic-green-muted` | colors |
|
|
36
|
-
| `--platform-colors-semantic-green-text` | colors |
|
|
37
|
-
| `--platform-colors-semantic-orange` | colors |
|
|
38
|
-
| `--platform-colors-semantic-orange-border` | colors |
|
|
39
|
-
| `--platform-colors-semantic-orange-muted` | colors |
|
|
40
|
-
| `--platform-colors-semantic-orange-text` | colors |
|
|
41
|
-
| `--platform-colors-semantic-red` | colors |
|
|
42
|
-
| `--platform-colors-semantic-red-border` | colors |
|
|
43
|
-
| `--platform-colors-semantic-red-muted` | colors |
|
|
44
|
-
| `--platform-colors-semantic-red-text` | colors |
|
|
45
|
-
| `--platform-colors-success` | colors |
|
|
46
|
-
| `--platform-colors-surface` | colors |
|
|
47
|
-
| `--platform-colors-surface-active` | colors |
|
|
48
|
-
| `--platform-colors-surface-hover` | colors |
|
|
49
|
-
| `--platform-colors-text` | colors |
|
|
50
|
-
| `--platform-colors-text-danger` | colors |
|
|
51
|
-
| `--platform-colors-text-disabled` | colors |
|
|
52
|
-
| `--platform-colors-text-inverse` | colors |
|
|
53
|
-
| `--platform-colors-text-secondary` | colors |
|
|
54
|
-
| `--platform-colors-warning` | colors |
|
|
55
|
-
| `--platform-radius-full` | radius |
|
|
56
|
-
| `--platform-radius-lg` | radius |
|
|
57
|
-
| `--platform-radius-md` | radius |
|
|
58
|
-
| `--platform-radius-sm` | radius |
|
|
59
|
-
| `--platform-shadow-lg` | shadow |
|
|
60
|
-
| `--platform-shadow-md` | shadow |
|
|
61
|
-
| `--platform-shadow-sm` | shadow |
|
|
62
|
-
| `--platform-spacing-lg` | spacing |
|
|
63
|
-
| `--platform-spacing-md` | spacing |
|
|
64
|
-
| `--platform-spacing-sm` | spacing |
|
|
65
|
-
| `--platform-spacing-xl` | spacing |
|
|
66
|
-
| `--platform-spacing-xs` | spacing |
|
|
67
|
-
| `--platform-spacing-xxl` | spacing |
|
|
68
|
-
| `--platform-transition-base` | transition |
|
|
69
|
-
| `--platform-transition-fast` | transition |
|
|
70
|
-
| `--platform-transition-slow` | transition |
|
|
71
|
-
| `--platform-typography-font-family` | typography |
|
|
72
|
-
| `--platform-typography-font-family-content` | typography |
|
|
73
|
-
| `--platform-typography-font-family-mono` | typography |
|
|
74
|
-
| `--platform-typography-font-size-base` | typography |
|
|
75
|
-
| `--platform-typography-font-size-lg` | typography |
|
|
76
|
-
| `--platform-typography-font-size-sm` | typography |
|
|
77
|
-
| `--platform-typography-font-size-xl` | typography |
|
|
78
|
-
| `--platform-typography-font-size-xs` | typography |
|
|
79
|
-
| `--platform-typography-font-weight-bold` | typography |
|
|
80
|
-
| `--platform-typography-font-weight-medium` | typography |
|
|
81
|
-
| `--platform-typography-font-weight-normal` | typography |
|
|
82
|
-
| `--platform-typography-line-height-base` | typography |
|
|
83
|
-
| `--platform-typography-line-height-tight` | typography |
|
|
84
|
-
| `--platform-z-index-zi-app-base` | zIndex |
|
|
85
|
-
| `--platform-z-index-zi-app-chrome` | zIndex |
|
|
86
|
-
| `--platform-z-index-zi-app-menus` | zIndex |
|
|
87
|
-
| `--platform-z-index-zi-app-modal` | zIndex |
|
|
88
|
-
| `--platform-z-index-zi-app-sidebar` | zIndex |
|
|
89
|
-
| `--platform-z-index-zi-app-toast` | zIndex |
|
|
90
|
-
| `--platform-z-index-zi-app-viewport-toolbar` | zIndex |
|
|
12
|
+
| Variable | Domain | Light value | Dark value |
|
|
13
|
+
| --- | --- | --- | --- |
|
|
14
|
+
| `--platform-colors-accent` | colors | `#1b1b1e` | `#e5e5e9` |
|
|
15
|
+
| `--platform-colors-accent-hover` | colors | `#1b1b1e` | `#eaeaee` |
|
|
16
|
+
| `--platform-colors-accent-muted` | colors | `#eaeaee` | `#313135` |
|
|
17
|
+
| `--platform-colors-app-viewport` | colors | `#fbfbfc` | `#202024` |
|
|
18
|
+
| `--platform-colors-bg` | colors | `#fbfbfc` | `#202024` |
|
|
19
|
+
| `--platform-colors-border` | colors | `#e5e5e9` | `#313135` |
|
|
20
|
+
| `--platform-colors-border-strong` | colors | `#dadade` | `#43434a` |
|
|
21
|
+
| `--platform-colors-chrome-tab-strip` | colors | `#ececef` | `#1b1b1e` |
|
|
22
|
+
| `--platform-colors-chrome-titlebar` | colors | `#fbfbfc` | `#202024` |
|
|
23
|
+
| `--platform-colors-danger` | colors | `#b23a2e` | `#e0796e` |
|
|
24
|
+
| `--platform-colors-divider` | colors | `#e5e5e9` | `#313135` |
|
|
25
|
+
| `--platform-colors-elevated` | colors | `#ffffff` | `#26262a` |
|
|
26
|
+
| `--platform-colors-focus` | colors | `#1b1b1e` | `#e5e5e9` |
|
|
27
|
+
| `--platform-colors-info` | colors | `#3b6fb0` | `#6fa0e0` |
|
|
28
|
+
| `--platform-colors-selection` | colors | `#eaeaee` | `#313135` |
|
|
29
|
+
| `--platform-colors-semantic-blue` | colors | `#3b6fb0` | `#6fa0e0` |
|
|
30
|
+
| `--platform-colors-semantic-blue-border` | colors | `#b9cbe4` | `#365373` |
|
|
31
|
+
| `--platform-colors-semantic-blue-muted` | colors | `#e8f0fb` | `#1c2a3c` |
|
|
32
|
+
| `--platform-colors-semantic-blue-text` | colors | `#244f87` | `#a8c8f0` |
|
|
33
|
+
| `--platform-colors-semantic-green` | colors | `#1f8a55` | `#57b988` |
|
|
34
|
+
| `--platform-colors-semantic-green-border` | colors | `#1f8a55` | `#32684d` |
|
|
35
|
+
| `--platform-colors-semantic-green-muted` | colors | `#eef7f1` | `#18342a` |
|
|
36
|
+
| `--platform-colors-semantic-green-text` | colors | `#16683f` | `#8fe0b6` |
|
|
37
|
+
| `--platform-colors-semantic-orange` | colors | `#c98a2b` | `#e0b257` |
|
|
38
|
+
| `--platform-colors-semantic-orange-border` | colors | `#e3c98f` | `#6d5b2f` |
|
|
39
|
+
| `--platform-colors-semantic-orange-muted` | colors | `#f3e5c8` | `#3a3322` |
|
|
40
|
+
| `--platform-colors-semantic-orange-text` | colors | `#7a5114` | `#f0ce8a` |
|
|
41
|
+
| `--platform-colors-semantic-red` | colors | `#b23a2e` | `#e0796e` |
|
|
42
|
+
| `--platform-colors-semantic-red-border` | colors | `#dfb7b1` | `#753f38` |
|
|
43
|
+
| `--platform-colors-semantic-red-muted` | colors | `#f4dfdc` | `#3a211d` |
|
|
44
|
+
| `--platform-colors-semantic-red-text` | colors | `#8a2d24` | `#f0a89e` |
|
|
45
|
+
| `--platform-colors-success` | colors | `#1f8a55` | `#57b988` |
|
|
46
|
+
| `--platform-colors-surface` | colors | `#f8f8fa` | `#26262a` |
|
|
47
|
+
| `--platform-colors-surface-active` | colors | `#eaeaee` | `#161619` |
|
|
48
|
+
| `--platform-colors-surface-hover` | colors | `#eaeaee` | `#2c2c30` |
|
|
49
|
+
| `--platform-colors-text` | colors | `#1b1b1e` | `#ececef` |
|
|
50
|
+
| `--platform-colors-text-danger` | colors | `#b23a2e` | `#e0796e` |
|
|
51
|
+
| `--platform-colors-text-disabled` | colors | `#9a9aa0` | `#6e6e74` |
|
|
52
|
+
| `--platform-colors-text-inverse` | colors | `#ffffff` | `#1b1b1e` |
|
|
53
|
+
| `--platform-colors-text-secondary` | colors | `#3a3a3e` | `#c9c9cf` |
|
|
54
|
+
| `--platform-colors-warning` | colors | `#c98a2b` | `#e0b257` |
|
|
55
|
+
| `--platform-radius-full` | radius | `999px` | `999px` |
|
|
56
|
+
| `--platform-radius-lg` | radius | `0px` | `0px` |
|
|
57
|
+
| `--platform-radius-md` | radius | `0px` | `0px` |
|
|
58
|
+
| `--platform-radius-sm` | radius | `0px` | `0px` |
|
|
59
|
+
| `--platform-shadow-lg` | shadow | `0 18px 48px rgb(18 18 22 / 0.13)` | `0 18px 44px rgba(0, 0, 0, 0.38)` |
|
|
60
|
+
| `--platform-shadow-md` | shadow | `0 8px 24px rgb(18 18 22 / 0.08)` | `0 8px 24px rgba(0, 0, 0, 0.3)` |
|
|
61
|
+
| `--platform-shadow-sm` | shadow | `none` | `none` |
|
|
62
|
+
| `--platform-spacing-lg` | spacing | `16px` | `16px` |
|
|
63
|
+
| `--platform-spacing-md` | spacing | `12px` | `12px` |
|
|
64
|
+
| `--platform-spacing-sm` | spacing | `8px` | `8px` |
|
|
65
|
+
| `--platform-spacing-xl` | spacing | `24px` | `24px` |
|
|
66
|
+
| `--platform-spacing-xs` | spacing | `4px` | `4px` |
|
|
67
|
+
| `--platform-spacing-xxl` | spacing | `32px` | `32px` |
|
|
68
|
+
| `--platform-transition-base` | transition | `200ms ease` | `200ms ease` |
|
|
69
|
+
| `--platform-transition-fast` | transition | `120ms ease` | `120ms ease` |
|
|
70
|
+
| `--platform-transition-slow` | transition | `320ms ease` | `320ms ease` |
|
|
71
|
+
| `--platform-typography-font-family` | typography | `"Archivo", system-ui, -apple-system, "Segoe UI", sans-serif` | `"Archivo", system-ui, -apple-system, "Segoe UI", sans-serif` |
|
|
72
|
+
| `--platform-typography-font-family-content` | typography | `'Source Serif 4', Georgia, serif` | `'Source Serif 4', Georgia, serif` |
|
|
73
|
+
| `--platform-typography-font-family-mono` | typography | `'JetBrains Mono', ui-monospace, monospace` | `'JetBrains Mono', ui-monospace, monospace` |
|
|
74
|
+
| `--platform-typography-font-size-base` | typography | `14.5px` | `14.5px` |
|
|
75
|
+
| `--platform-typography-font-size-lg` | typography | `17px` | `17px` |
|
|
76
|
+
| `--platform-typography-font-size-sm` | typography | `13px` | `13px` |
|
|
77
|
+
| `--platform-typography-font-size-xl` | typography | `24px` | `24px` |
|
|
78
|
+
| `--platform-typography-font-size-xs` | typography | `11px` | `11px` |
|
|
79
|
+
| `--platform-typography-font-weight-bold` | typography | `600` | `600` |
|
|
80
|
+
| `--platform-typography-font-weight-medium` | typography | `500` | `500` |
|
|
81
|
+
| `--platform-typography-font-weight-normal` | typography | `400` | `400` |
|
|
82
|
+
| `--platform-typography-line-height-base` | typography | `1.6` | `1.6` |
|
|
83
|
+
| `--platform-typography-line-height-tight` | typography | `1.25` | `1.25` |
|
|
84
|
+
| `--platform-z-index-zi-app-base` | zIndex | `0` | `0` |
|
|
85
|
+
| `--platform-z-index-zi-app-chrome` | zIndex | `20` | `20` |
|
|
86
|
+
| `--platform-z-index-zi-app-menus` | zIndex | `100` | `100` |
|
|
87
|
+
| `--platform-z-index-zi-app-modal` | zIndex | `300` | `300` |
|
|
88
|
+
| `--platform-z-index-zi-app-sidebar` | zIndex | `10` | `10` |
|
|
89
|
+
| `--platform-z-index-zi-app-toast` | zIndex | `200` | `200` |
|
|
90
|
+
| `--platform-z-index-zi-app-viewport-toolbar` | zIndex | `25` | `25` |
|
|
91
91
|
|
|
92
92
|
## App-Owned Colors
|
|
93
93
|
|
|
@@ -1,124 +1,124 @@
|
|
|
1
|
-
# Tool Handlers
|
|
2
|
-
|
|
3
|
-
App agent tools have two halves:
|
|
4
|
-
|
|
5
|
-
- `plugin.json` declares the tool schema for the shell agent.
|
|
6
|
-
- app source registers a runtime handler after the iframe bridge is ready.
|
|
7
|
-
|
|
8
|
-
The names must match exactly.
|
|
9
|
-
|
|
10
|
-
## Generated Structure
|
|
11
|
-
|
|
12
|
-
When the manifest includes `app.agents.tools`, the generator creates this
|
|
13
|
-
structure and wires `useAppAgentTools(ready)` into `src/App.tsx`:
|
|
14
|
-
|
|
15
|
-
```text
|
|
16
|
-
src/
|
|
17
|
-
agents/
|
|
18
|
-
catalog.ts
|
|
19
|
-
handlers/
|
|
20
|
-
index.ts
|
|
21
|
-
hooks/
|
|
22
|
-
useAppAgentTools.ts
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
## Catalog
|
|
26
|
-
|
|
27
|
-
Generated from manifest tool names:
|
|
28
|
-
|
|
29
|
-
```ts
|
|
30
|
-
export const APP_AGENT_TOOL_NAMES = ['listItems'] as const
|
|
31
|
-
|
|
32
|
-
export const APP_AGENT_LOG_LABEL = '{{APP_SLUG}}'
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
Keep this list in the same order as `plugin.json` `app.agents.tools`.
|
|
36
|
-
|
|
37
|
-
## Registration Hook
|
|
38
|
-
|
|
39
|
-
Generated when tools exist:
|
|
40
|
-
|
|
41
|
-
```ts
|
|
42
|
-
import { usePlatformAgentTools } from '@puredesktop/puredesktop-ui-bridge/bridge/react/usePlatformAgentTools'
|
|
43
|
-
import { APP_AGENT_LOG_LABEL, APP_AGENT_TOOL_NAMES } from '../agents/catalog'
|
|
44
|
-
import { appAgentHandlers } from '../agents/handlers'
|
|
45
|
-
|
|
46
|
-
export function useAppAgentTools(ready: boolean): void {
|
|
47
|
-
usePlatformAgentTools({
|
|
48
|
-
ready,
|
|
49
|
-
tools: APP_AGENT_TOOL_NAMES,
|
|
50
|
-
logLabel: APP_AGENT_LOG_LABEL,
|
|
51
|
-
handlers: appAgentHandlers,
|
|
52
|
-
})
|
|
53
|
-
}
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
Call this hook from `src/App.tsx` after `usePlatformBridge()`:
|
|
57
|
-
|
|
58
|
-
```ts
|
|
59
|
-
useAppAgentTools(ready)
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
## Handler Shape
|
|
63
|
-
|
|
64
|
-
Generated handlers start as explicit not-implemented tool errors. Replace each
|
|
65
|
-
stub with app domain logic.
|
|
66
|
-
|
|
67
|
-
```ts
|
|
68
|
-
import {
|
|
69
|
-
agentToolErrorContent,
|
|
70
|
-
formatAgentToolJson,
|
|
71
|
-
readAgentToolStringArg,
|
|
72
|
-
} from '@puredesktop/puredesktop-ui-bridge/bridge/agentToolHelpers'
|
|
73
|
-
import type { AgentToolHandler } from '@puredesktop/puredesktop-ui-bridge/bridge/react/usePlatformAgentTools'
|
|
74
|
-
|
|
75
|
-
const listItems: AgentToolHandler = async invoke => {
|
|
76
|
-
const status = readAgentToolStringArg(invoke.arguments, 'status')
|
|
77
|
-
|
|
78
|
-
return {
|
|
79
|
-
content: formatAgentToolJson({
|
|
80
|
-
items: [],
|
|
81
|
-
status: status || null,
|
|
82
|
-
}),
|
|
83
|
-
}
|
|
84
|
-
}
|
|
85
|
-
|
|
86
|
-
export const appAgentHandlers = {
|
|
87
|
-
listItems,
|
|
88
|
-
} satisfies Record<string, AgentToolHandler>
|
|
89
|
-
```
|
|
90
|
-
|
|
91
|
-
Return compact JSON for structured data. Return `agentToolErrorContent(message)`
|
|
92
|
-
for validation failures that the agent can correct.
|
|
93
|
-
|
|
94
|
-
## Read Tool Pattern
|
|
95
|
-
|
|
96
|
-
Read tools return current app state, ids, paths, and exact values needed before a
|
|
97
|
-
write. The agent needs stable ids and exact target names.
|
|
98
|
-
|
|
99
|
-
## Write Tool Pattern
|
|
100
|
-
|
|
101
|
-
Write tools validate precise targets. A write handler returns a short result
|
|
102
|
-
with the changed id/path and enough data for the agent to explain what changed.
|
|
103
|
-
|
|
104
|
-
Manifest write tools that mutate files, records, external services, or broad app
|
|
105
|
-
state set `requiresApproval: true` unless the action is intentionally safe.
|
|
106
|
-
|
|
107
|
-
## Validation
|
|
108
|
-
|
|
1
|
+
# Tool Handlers
|
|
2
|
+
|
|
3
|
+
App agent tools have two halves:
|
|
4
|
+
|
|
5
|
+
- `plugin.json` declares the tool schema for the shell agent.
|
|
6
|
+
- app source registers a runtime handler after the iframe bridge is ready.
|
|
7
|
+
|
|
8
|
+
The names must match exactly.
|
|
9
|
+
|
|
10
|
+
## Generated Structure
|
|
11
|
+
|
|
12
|
+
When the manifest includes `app.agents.tools`, the generator creates this
|
|
13
|
+
structure and wires `useAppAgentTools(ready)` into `src/App.tsx`:
|
|
14
|
+
|
|
15
|
+
```text
|
|
16
|
+
src/
|
|
17
|
+
agents/
|
|
18
|
+
catalog.ts
|
|
19
|
+
handlers/
|
|
20
|
+
index.ts
|
|
21
|
+
hooks/
|
|
22
|
+
useAppAgentTools.ts
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
## Catalog
|
|
26
|
+
|
|
27
|
+
Generated from manifest tool names:
|
|
28
|
+
|
|
29
|
+
```ts
|
|
30
|
+
export const APP_AGENT_TOOL_NAMES = ['listItems'] as const
|
|
31
|
+
|
|
32
|
+
export const APP_AGENT_LOG_LABEL = '{{APP_SLUG}}'
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Keep this list in the same order as `plugin.json` `app.agents.tools`.
|
|
36
|
+
|
|
37
|
+
## Registration Hook
|
|
38
|
+
|
|
39
|
+
Generated when tools exist:
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
import { usePlatformAgentTools } from '@puredesktop/puredesktop-ui-bridge/bridge/react/usePlatformAgentTools'
|
|
43
|
+
import { APP_AGENT_LOG_LABEL, APP_AGENT_TOOL_NAMES } from '../agents/catalog'
|
|
44
|
+
import { appAgentHandlers } from '../agents/handlers'
|
|
45
|
+
|
|
46
|
+
export function useAppAgentTools(ready: boolean): void {
|
|
47
|
+
usePlatformAgentTools({
|
|
48
|
+
ready,
|
|
49
|
+
tools: APP_AGENT_TOOL_NAMES,
|
|
50
|
+
logLabel: APP_AGENT_LOG_LABEL,
|
|
51
|
+
handlers: appAgentHandlers,
|
|
52
|
+
})
|
|
53
|
+
}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Call this hook from `src/App.tsx` after `usePlatformBridge()`:
|
|
57
|
+
|
|
58
|
+
```ts
|
|
59
|
+
useAppAgentTools(ready)
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## Handler Shape
|
|
63
|
+
|
|
64
|
+
Generated handlers start as explicit not-implemented tool errors. Replace each
|
|
65
|
+
stub with app domain logic.
|
|
66
|
+
|
|
67
|
+
```ts
|
|
68
|
+
import {
|
|
69
|
+
agentToolErrorContent,
|
|
70
|
+
formatAgentToolJson,
|
|
71
|
+
readAgentToolStringArg,
|
|
72
|
+
} from '@puredesktop/puredesktop-ui-bridge/bridge/agentToolHelpers'
|
|
73
|
+
import type { AgentToolHandler } from '@puredesktop/puredesktop-ui-bridge/bridge/react/usePlatformAgentTools'
|
|
74
|
+
|
|
75
|
+
const listItems: AgentToolHandler = async invoke => {
|
|
76
|
+
const status = readAgentToolStringArg(invoke.arguments, 'status')
|
|
77
|
+
|
|
78
|
+
return {
|
|
79
|
+
content: formatAgentToolJson({
|
|
80
|
+
items: [],
|
|
81
|
+
status: status || null,
|
|
82
|
+
}),
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
export const appAgentHandlers = {
|
|
87
|
+
listItems,
|
|
88
|
+
} satisfies Record<string, AgentToolHandler>
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Return compact JSON for structured data. Return `agentToolErrorContent(message)`
|
|
92
|
+
for validation failures that the agent can correct.
|
|
93
|
+
|
|
94
|
+
## Read Tool Pattern
|
|
95
|
+
|
|
96
|
+
Read tools return current app state, ids, paths, and exact values needed before a
|
|
97
|
+
write. The agent needs stable ids and exact target names.
|
|
98
|
+
|
|
99
|
+
## Write Tool Pattern
|
|
100
|
+
|
|
101
|
+
Write tools validate precise targets. A write handler returns a short result
|
|
102
|
+
with the changed id/path and enough data for the agent to explain what changed.
|
|
103
|
+
|
|
104
|
+
Manifest write tools that mutate files, records, external services, or broad app
|
|
105
|
+
state set `requiresApproval: true` unless the action is intentionally safe.
|
|
106
|
+
|
|
107
|
+
## Validation
|
|
108
|
+
|
|
109
109
|
`npm run puredesktop:check` verifies declared tool names appear in source and in
|
|
110
110
|
the built output. For generated tool scaffolds, it also verifies:
|
|
111
|
-
|
|
112
|
-
- `src/agents/catalog.ts` exports `APP_AGENT_TOOL_NAMES`;
|
|
113
|
-
- every manifest tool name appears in the catalog;
|
|
114
|
-
- `src/agents/handlers/index.ts` exports `appAgentHandlers`;
|
|
115
|
-
- every manifest tool name appears in the handler map;
|
|
116
|
-
- `src/hooks/useAppAgentTools.ts` registers with `usePlatformAgentTools`;
|
|
117
|
-
- `src/App.tsx` calls `useAppAgentTools(ready)`.
|
|
118
|
-
|
|
119
|
-
Build before running it:
|
|
120
|
-
|
|
121
|
-
```bash
|
|
122
|
-
npm run build
|
|
123
|
-
npm run puredesktop:check
|
|
124
|
-
```
|
|
111
|
+
|
|
112
|
+
- `src/agents/catalog.ts` exports `APP_AGENT_TOOL_NAMES`;
|
|
113
|
+
- every manifest tool name appears in the catalog;
|
|
114
|
+
- `src/agents/handlers/index.ts` exports `appAgentHandlers`;
|
|
115
|
+
- every manifest tool name appears in the handler map;
|
|
116
|
+
- `src/hooks/useAppAgentTools.ts` registers with `usePlatformAgentTools`;
|
|
117
|
+
- `src/App.tsx` calls `useAppAgentTools(ready)`.
|
|
118
|
+
|
|
119
|
+
Build before running it:
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
npm run build
|
|
123
|
+
npm run puredesktop:check
|
|
124
|
+
```
|