@jay-framework/aiditor 0.20.0 → 0.22.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/dist/actions/cancel-agent-task.jay-action +1 -0
- package/dist/actions/cancel-agent-task.jay-action.d.ts +1 -0
- package/dist/agent-kit-template/plugin/aiditor-add-menu.md +470 -63
- package/dist/index.client.d.ts +254 -16
- package/dist/index.client.js +3323 -1359
- package/dist/index.d.ts +29 -29
- package/dist/index.js +180 -162
- package/dist/pages/aiditor/page.css +127 -22
- package/dist/pages/aiditor/page.jay-html +853 -171
- package/dist/pages/aiditor/page.jay-html.d.ts +254 -16
- package/package.json +11 -10
- package/plugin.yaml +2 -3
|
@@ -1,96 +1,375 @@
|
|
|
1
1
|
# AIditor Add Menu — plugin contributor guide
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Audience:** Plugin authors and AI agents integrating Jay plugins with AIditor.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
**Installed at:** `agent-kit/plugin/aiditor-add-menu.md` when you run `jay-stack setup aiditor`.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
**Keep this file current:** When you change Add Menu behavior, schema, surfaces, or validation, update **this guide** in the same change. This file is the **operational source of truth** for contributors.
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
- **Q8:** Dynamic route segments (`[slug]`, `[prefix]`, …) are edited in the **page route** / **planned route** field — not on catalog items.
|
|
9
|
+
---
|
|
11
10
|
|
|
12
|
-
##
|
|
11
|
+
## What is the Add Menu?
|
|
13
12
|
|
|
14
|
-
|
|
13
|
+
The Add Menu is AIditor's extension point for **plugin-contributed agent context**. Each catalog **item** is a user-selectable entry with:
|
|
14
|
+
|
|
15
|
+
- **`title`** and **`category`** / **`subCategory`** — discovery and navigation labels (not a type system)
|
|
16
|
+
- **`prompt`** — complete agent instructions, injected **verbatim** when the user attaches the item
|
|
17
|
+
|
|
18
|
+
There are **no mini-forms** and **no `parameters` field** on catalog items. Plugins **materialize** URLs, contract keys, Wix IDs, and instructions into `prompt` at **agent-kit generation time** (or via a plugin rebuild command).
|
|
19
|
+
|
|
20
|
+
When the user picks an item, AIditor adds a **chip** to the request. On submit, each attachment becomes a `## Add Menu attachments` block in the agent task.
|
|
21
|
+
|
|
22
|
+
**Agent behavior rule:** One attachment = one **resource in scope**. The user may describe multiple uses in prose; the agent wires only what the user referenced — not every attached item automatically.
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## How it works
|
|
27
|
+
|
|
28
|
+
```mermaid
|
|
29
|
+
flowchart LR
|
|
30
|
+
subgraph plugin [Contributing plugin]
|
|
31
|
+
T[add-menu.template.yaml in package]
|
|
32
|
+
AK[agentkit handler]
|
|
33
|
+
end
|
|
34
|
+
subgraph project [Jay project]
|
|
35
|
+
Y[agent-kit/aiditor/add-menu/*.yaml]
|
|
36
|
+
IMG[agent-kit/aiditor/thumbnails/]
|
|
37
|
+
PUB[public/aiditor-add-menu-thumbnails/]
|
|
38
|
+
end
|
|
39
|
+
subgraph aiditor [AIditor]
|
|
40
|
+
L[listAddMenuItems]
|
|
41
|
+
UI[+ Add / picker / @ / chips]
|
|
42
|
+
AG[Agent prompt]
|
|
43
|
+
end
|
|
44
|
+
T --> AK
|
|
45
|
+
AK --> Y
|
|
46
|
+
AK --> IMG
|
|
47
|
+
AK --> PUB
|
|
48
|
+
Y --> L
|
|
49
|
+
IMG --> L
|
|
50
|
+
L --> UI
|
|
51
|
+
UI -->|user attaches| AG
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
1. **Plugin ships a template** — `agent-kit/aiditor/add-menu.template.yaml` (and optional thumbnails) inside the npm package.
|
|
55
|
+
2. **`jay-stack agent-kit`** (project `yarn agent-kit`) runs each plugin's **agent-kit handler** (`agentkit` in `plugin.yaml`) — writes `<pluginName>.yaml` under `agent-kit/aiditor/add-menu/`, copies thumbnails.
|
|
56
|
+
3. **`jay-stack setup <plugin>`** is for **config and credentials only** — it must **not** write add-menu catalogs.
|
|
57
|
+
4. **AIditor reads** all `*.yaml` in that directory at runtime via `listAddMenuItems`.
|
|
58
|
+
5. **Visibility filter** — items appear only when their `packageName` / `pluginName` matches an **installed** plugin (`package.json` or `src/plugins/<name>/`).
|
|
59
|
+
6. **User attaches** items via Add Menu surfaces; **`prompt` is injected** into the agent task.
|
|
60
|
+
|
|
61
|
+
**Dynamic route segments** (`[slug]`, `[category]`, …) are edited in the **page route** / **planned route** fields — not on catalog items. Use id convention `<pluginName>:<contractName>` so AIditor can resolve contract params (see [Contract lookup](#contract-lookup)).
|
|
62
|
+
|
|
63
|
+
### Plugin phases (locked)
|
|
64
|
+
|
|
65
|
+
| `plugin.yaml` | CLI | Responsibility |
|
|
66
|
+
| ------------- | --- | -------------- |
|
|
67
|
+
| `plugin.yaml` key | CLI | Responsibility |
|
|
68
|
+
| ----------------- | --- | -------------- |
|
|
69
|
+
| `setup` | `jay-stack setup <plugin>` | Config files, credential validation — **not** add-menu catalogs |
|
|
70
|
+
| `agentkit` | `jay-stack agent-kit` | Write `agent-kit/aiditor/add-menu/*.yaml`, thumbnails, reference data |
|
|
71
|
+
|
|
72
|
+
Plugins that ship `add-menu.template.yaml` **must** declare `agentkit` pointing at an agent-kit handler. `jay-stack validate-plugin` warns when the handler is missing.
|
|
73
|
+
|
|
74
|
+
**Reference implementations:** `@jay-framework/wix-media` (generated catalog), `@jay-framework/design-system-validator` (DESIGN.md tokens), `@jay-framework/ui-kit` and `@jay-framework/wix-stores` (static template + thumbnails in references handler).
|
|
75
|
+
|
|
76
|
+
---
|
|
77
|
+
|
|
78
|
+
## Quick start — add items from your plugin
|
|
79
|
+
|
|
80
|
+
### 1. Add a catalog template to your package
|
|
81
|
+
|
|
82
|
+
```
|
|
83
|
+
packages/<your-plugin>/
|
|
84
|
+
agent-kit/aiditor/
|
|
85
|
+
add-menu.template.yaml # static items (validated by validate-plugin)
|
|
86
|
+
thumbnails/<your-plugin>/… # images, GIFs, posters (optional)
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
For **dynamic** items (e.g. one row per Wix media file), the agent-kit handler also writes:
|
|
15
90
|
|
|
16
91
|
```
|
|
17
92
|
<project>/agent-kit/aiditor/add-menu/
|
|
18
|
-
<pluginName>.yaml
|
|
19
|
-
|
|
93
|
+
<pluginName>.generated.yaml
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
### 2. Implement the agent-kit handler
|
|
97
|
+
|
|
98
|
+
In `plugin.yaml`:
|
|
99
|
+
|
|
100
|
+
```yaml
|
|
101
|
+
setup: setupMyPlugin # config + credentials only
|
|
102
|
+
agentkit: generateMyAgentKit # add-menu + discovery data
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
The handler runs on `jay-stack agent-kit`:
|
|
106
|
+
|
|
107
|
+
1. Create `<project>/agent-kit/aiditor/add-menu/` if missing.
|
|
108
|
+
2. Copy `add-menu.template.yaml` → `<project>/agent-kit/aiditor/add-menu/<pluginName>.yaml` (skip if exists unless `ctx.force`).
|
|
109
|
+
3. Copy thumbnails to `agent-kit/aiditor/thumbnails/` and `public/aiditor-add-menu-thumbnails/` (idempotent).
|
|
110
|
+
4. Optionally write `<pluginName>.generated.yaml` from live service data.
|
|
111
|
+
|
|
112
|
+
Export the handler from the package entry (`lib/index.ts`).
|
|
113
|
+
|
|
114
|
+
### 3. Validate — `jay-stack validate-plugin` only
|
|
115
|
+
|
|
116
|
+
When your package includes `agent-kit/aiditor/add-menu.template.yaml` or `add-menu.yaml`, **`jay-stack validate-plugin`** automatically:
|
|
117
|
+
|
|
118
|
+
- Validates catalog **schema** (required fields, `folderPath`, `interaction`, `presentation`, `browse`)
|
|
119
|
+
- Runs **lint** rules (gif poster, html-fragment safety, browse size hints)
|
|
120
|
+
- Warns if `agentkit` is missing (catalog must not be generated in setup)
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
jay-stack validate-plugin
|
|
124
|
+
# or from package root:
|
|
125
|
+
yarn validate
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
Use `--strict` to fail on warnings (recommended in CI once warnings are clean).
|
|
129
|
+
|
|
130
|
+
**Source of truth:** validation lives in `@jay-framework/plugin-validator` (`add-menu-catalog-lint.ts`). AIditor runtime uses the same module when loading project catalogs — there is no separate AIditor-only schema.
|
|
131
|
+
|
|
132
|
+
### 4. Verify in AIditor
|
|
133
|
+
|
|
134
|
+
1. Ensure plugin and aiditor are in the project `package.json`.
|
|
135
|
+
2. Run `yarn agent-kit` (or `jay-stack agent-kit`) to materialize catalogs.
|
|
136
|
+
3. Open AIditor → **+ Add** or Add Page **Add Menu** → items appear under your `category`.
|
|
137
|
+
4. Click **Refresh catalog** after editing project yaml during development.
|
|
138
|
+
|
|
139
|
+
---
|
|
140
|
+
|
|
141
|
+
## File layout
|
|
142
|
+
|
|
143
|
+
### Project paths (written by agent-kit handler)
|
|
144
|
+
|
|
145
|
+
```
|
|
146
|
+
<project>/agent-kit/aiditor/
|
|
147
|
+
add-menu/
|
|
148
|
+
wix-stores.yaml # one file per plugin (convention)
|
|
149
|
+
wix-media.generated.yaml # optional dynamic catalog
|
|
150
|
+
thumbnails/<plugin>/… # image / gif / poster assets
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
```
|
|
154
|
+
<project>/public/aiditor-add-menu-thumbnails/<plugin>/…
|
|
20
155
|
```
|
|
21
156
|
|
|
22
|
-
|
|
157
|
+
**Html-fragment preview markup** lives **inline in catalog yaml** (`presentation.html`) — there is no separate `previews/*.html` path.
|
|
23
158
|
|
|
24
|
-
|
|
159
|
+
### Merge rules
|
|
160
|
+
|
|
161
|
+
- AIditor reads every `*.yaml` / `*.yml` in `add-menu/`.
|
|
162
|
+
- Files are merged in **lexicographic path order**.
|
|
163
|
+
- **Duplicate `id`:** later file wins (warning logged).
|
|
164
|
+
- Items are grouped by `category` → `subCategory` (merged **across plugins** when `category` / `subCategory` strings match exactly).
|
|
165
|
+
- Within a subCategory, browse order follows **yaml declaration order** in each catalog file (files merged lexicographically). Do not rely on alphabetical `title` order.
|
|
166
|
+
|
|
167
|
+
Browse left sidebar shows **`category`** labels — not `pluginName`. Prefer product-facing categories (`Store`, `UI Kit`) over package names.
|
|
168
|
+
|
|
169
|
+
### `subCategory` vs `folderPath`
|
|
170
|
+
|
|
171
|
+
Use **both together** when a plugin has many items:
|
|
172
|
+
|
|
173
|
+
| Field | Purpose | Example |
|
|
174
|
+
| ----- | ------- | ------- |
|
|
175
|
+
| **`subCategory`** | Optional coarse type filter (horizontal chips) | `Images`, `Videos`, `Components` |
|
|
176
|
+
| **`folderPath`** | Plugin-owned recursive folder tree (main grid drill-down) | `["Marketing", "Campaigns"]` |
|
|
177
|
+
|
|
178
|
+
- **`folderPath`** is navigation only — not attachable; folders are derived from item paths (no folder-only yaml rows).
|
|
179
|
+
- Omit **`folderPath`** for small catalogs (e.g. wix-stores components).
|
|
180
|
+
- **wix-media** generated items set **`folderPath`** from the Wix Media Manager parent chain. Do **not** include a top-level `Site Files` container segment — browse root shows first-level folders and loose files. Omit **`subCategory`** on wix-media items — browse by folders only.
|
|
181
|
+
- **Sub-category filter chips** appear only when a category has **two or more** distinct `subCategory` buckets. Items with omitted `subCategory` group into one implicit **General** bucket; if that is the only bucket, the chip row is hidden (folder navigation only).
|
|
182
|
+
|
|
183
|
+
---
|
|
184
|
+
|
|
185
|
+
## Catalog schema
|
|
25
186
|
|
|
26
187
|
Each file:
|
|
27
188
|
|
|
28
189
|
```yaml
|
|
29
190
|
items:
|
|
30
|
-
- id: <pluginName>:<slug>
|
|
31
|
-
title: User-facing label
|
|
32
|
-
category: Store
|
|
33
|
-
prompt: |
|
|
34
|
-
Complete agent instructions (markdown)
|
|
35
|
-
pluginName: wix-stores
|
|
191
|
+
- id: <pluginName>:<slug> # required — stable, unique
|
|
192
|
+
title: User-facing label # required
|
|
193
|
+
category: Store # required — top-level nav label
|
|
194
|
+
prompt: | # required — injected verbatim
|
|
195
|
+
Complete agent instructions (markdown).
|
|
196
|
+
pluginName: wix-stores # recommended
|
|
36
197
|
packageName: "@jay-framework/wix-stores"
|
|
37
|
-
subCategory: Components
|
|
38
|
-
|
|
39
|
-
|
|
198
|
+
subCategory: Components # optional — second nav level (type filter)
|
|
199
|
+
folderPath: # optional — recursive folder drill-down
|
|
200
|
+
- Marketing
|
|
201
|
+
- Campaigns
|
|
202
|
+
thumbnail: thumbnails/... # optional — legacy; prefer presentation
|
|
203
|
+
presentation: # optional — browse grid preview
|
|
204
|
+
type: image | gif | html-fragment
|
|
205
|
+
src: thumbnails/... # image | gif
|
|
206
|
+
poster: thumbnails/... # gif only — recommended
|
|
207
|
+
html: | # html-fragment only — inline markup
|
|
208
|
+
<div class="am-preview">…</div>
|
|
209
|
+
browse: # optional — browse grid footprint
|
|
210
|
+
size: large | medium | small # default: medium
|
|
211
|
+
interaction: # optional — how user attaches
|
|
40
212
|
mode: reference | stage-place
|
|
41
|
-
|
|
42
|
-
stagePromptTemplate: | # stage-place only — prefilled marker instruction
|
|
213
|
+
stagePromptTemplate: | # stage-place only
|
|
43
214
|
Add spring effect at this location.
|
|
44
215
|
```
|
|
45
216
|
|
|
46
|
-
|
|
217
|
+
### Required fields
|
|
218
|
+
|
|
219
|
+
`id`, `title`, `category`, `prompt`
|
|
220
|
+
|
|
221
|
+
### Rejected fields (validation errors)
|
|
222
|
+
|
|
223
|
+
| Field / pattern | Code | Why |
|
|
224
|
+
| --------------- | ---- | --- |
|
|
225
|
+
| `kind` | `rejected-field-kind` | No core type enum — express intent in `prompt` |
|
|
226
|
+
| `parameters` | `rejected-field-parameters` | No mini-forms — bake values into `prompt` |
|
|
227
|
+
| `component` | `rejected-field-component` | Use `prompt` + contract paths |
|
|
228
|
+
| `allowedScopes` | `rejected-field-allowedScopes` | Attachments are request-level or per-marker via UI |
|
|
229
|
+
|
|
230
|
+
---
|
|
231
|
+
|
|
232
|
+
## AIditor surfaces
|
|
233
|
+
|
|
234
|
+
One catalog, **different views**. Plugins do **not** ship separate manifests per surface.
|
|
235
|
+
|
|
236
|
+
| Surface | What the user does | Which items appear | Preview rendering |
|
|
237
|
+
| ------- | ------------------ | ------------------ | ----------------- |
|
|
238
|
+
| **Add Menu picker** (Add Page rail, change-request panel) | Browse and attach chips | All **browsable** items — excludes `subCategory: Categories` and ids containing `:category:` | Full `presentation` (image, gif, html-fragment) |
|
|
239
|
+
| **+ Add dock** (preview overlay) | Drag or click to **place on stage** | **`stage-place` only** (subset of browsable) | Full `presentation` |
|
|
240
|
+
| **`@` autocomplete** (marker / markdown fields) | Insert `@{title}` reference | **Full catalog** including category rows | Static image only (`image` src or gif `poster`) — no live GIF or html-fragment |
|
|
241
|
+
| **Attachment chips** | Shows what's attached | Attached items | Static thumb only |
|
|
242
|
+
| **Page Info** | Route + contract explorer from `jay-html` | Headless contracts detected automatically — **no catalog entry required** | n/a |
|
|
47
243
|
|
|
48
|
-
|
|
49
|
-
| --------------------- | ----------------------------------------------------------------------------- | ----------- |
|
|
50
|
-
| `mode` | `reference` — `@` mention in markers; click in + Add dock when marker focused | `reference` |
|
|
51
|
-
| | `stage-place` — click or drag onto preview creates a marker | |
|
|
52
|
-
| `persistOnPage` | **Deprecated (DL #26)** — ignored; no disk registry | n/a |
|
|
53
|
-
| `stagePromptTemplate` | Prefilled marker instruction for `stage-place` | item title |
|
|
244
|
+
### `@` autocomplete navigation
|
|
54
245
|
|
|
55
|
-
|
|
246
|
+
`@` drill-down uses the **same discovery hierarchy** as Add Menu browse (categories, sub-categories, folders, then leaves):
|
|
56
247
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
| **`@` autocomplete** | Full catalog reference | `mode: reference` (default); categories / high-cardinality → rely on `@` only (`subCategory: Categories` filtered from + Add grid) |
|
|
248
|
+
1. **Categories** — root list; exact `category` strings merged across all installed plugins (product-facing names like `Store`, `Effects` — not package or plugin names).
|
|
249
|
+
2. **Sub-categories** — within the selected category when **two or more** distinct buckets exist; exact `subCategory` strings merged across plugins (`null` / omitted → label **General**). Skipped when only one bucket.
|
|
250
|
+
3. **Folders** — within the selected sub-category (or category when sub-category chips are hidden); drill down `folderPath` segments the same way as the Add Menu picker and + Add dock.
|
|
251
|
+
4. **Leaves** — attachable items at the current folder path; yaml declaration order (not title sort).
|
|
62
252
|
|
|
63
|
-
|
|
253
|
+
When a category has only one sub-category bucket, `@` auto-skips to folders or leaves (same as browse hiding the chip row).
|
|
64
254
|
|
|
65
|
-
**
|
|
255
|
+
**Search mode** (non-empty query): flat leaf list — no drill-down; folder path appears in result labels when relevant.
|
|
66
256
|
|
|
67
|
-
|
|
257
|
+
Leaf rows show **`pluginName` as subtitle** on chips and in the autocomplete list.
|
|
68
258
|
|
|
69
|
-
|
|
259
|
+
### `interaction.mode`
|
|
70
260
|
|
|
71
|
-
|
|
261
|
+
| Mode | Default | User experience |
|
|
262
|
+
| ---- | ------- | --------------- |
|
|
263
|
+
| `reference` | **yes** | Attach as request context or `@` mention — no stage placement |
|
|
264
|
+
| `stage-place` | | Click or drag onto live preview → creates a marker with `stagePromptTemplate` (defaults to item title) |
|
|
72
265
|
|
|
73
|
-
|
|
74
|
-
| --------------- | -------------------------------- | ------------------------------ |
|
|
75
|
-
| Static template | `jay-stack setup <plugin>` | One item per headless contract |
|
|
76
|
-
| Generated file | setup `--force`, rebuild command | One item per Wix media file |
|
|
266
|
+
### High-cardinality items
|
|
77
267
|
|
|
78
|
-
|
|
268
|
+
Store **category** rows (`subCategory: Categories`, ids like `wix-stores:category:bedroom`) are **`@`-only** — too many for browse grids. AIditor filters them in code; plugins do not need a yaml flag.
|
|
79
269
|
|
|
80
|
-
|
|
270
|
+
---
|
|
81
271
|
|
|
82
|
-
|
|
272
|
+
## `presentation` — browse grid previews
|
|
83
273
|
|
|
84
|
-
|
|
85
|
-
2. Copy or generate `<pluginName>.yaml` from package template
|
|
86
|
-
3. Idempotent — skip if file exists unless `ctx.force`
|
|
87
|
-
4. Share generator with optional `rebuild-add-menu` command for `.generated.yaml`
|
|
274
|
+
Optional. Controls how an item **looks** in **Add Menu picker** and **+ Add dock** browse grids.
|
|
88
275
|
|
|
89
|
-
|
|
276
|
+
| `type` | Fields | Behavior |
|
|
277
|
+
| ------ | ------ | -------- |
|
|
278
|
+
| `image` | `src` | Static `<img>` |
|
|
279
|
+
| `gif` | `src`, optional `poster` | Autoplay GIF; `poster` when `prefers-reduced-motion: reduce` |
|
|
280
|
+
| `html-fragment` | **`html`** (inline yaml, required) | Live HTML/CSS demo via Jay `html-string` |
|
|
90
281
|
|
|
91
|
-
|
|
282
|
+
**Legacy `thumbnail`:** still accepted — `.gif` → `gif`; otherwise → `image`. New items should use explicit `presentation`.
|
|
92
283
|
|
|
93
|
-
**
|
|
284
|
+
**Not rendered on `@` autocomplete or chips** — those surfaces use title + optional static image only.
|
|
285
|
+
|
|
286
|
+
**Rejected:** top-level `kind`, `gif`, `htmlFragment` without `presentation` wrapper; `presentation.src` on `html-fragment` (use `html`).
|
|
287
|
+
|
|
288
|
+
### Html-fragment authoring
|
|
289
|
+
|
|
290
|
+
Put all preview markup in **`presentation.html`** as **one root `<div>`** with scoped styles:
|
|
291
|
+
|
|
292
|
+
```html
|
|
293
|
+
<div class="am-preview am-preview--{pluginName}-{slug}">
|
|
294
|
+
<style>
|
|
295
|
+
@scope (.am-preview) {
|
|
296
|
+
.am-preview {
|
|
297
|
+
display: flex;
|
|
298
|
+
align-items: center;
|
|
299
|
+
justify-content: center;
|
|
300
|
+
height: 100%;
|
|
301
|
+
}
|
|
302
|
+
.am-preview-btn {
|
|
303
|
+
padding: 10px 18px;
|
|
304
|
+
border-radius: 10px;
|
|
305
|
+
border: none;
|
|
306
|
+
background: #2563eb;
|
|
307
|
+
color: #fff;
|
|
308
|
+
}
|
|
309
|
+
}
|
|
310
|
+
</style>
|
|
311
|
+
<button type="button" class="am-preview-btn">Hover me</button>
|
|
312
|
+
</div>
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
| Rule | Why |
|
|
316
|
+
| ---- | --- |
|
|
317
|
+
| Single root `<div>` | Preview containment; validated |
|
|
318
|
+
| `<style>` with `@scope (.am-preview)` | Styles must not leak into Add Menu chrome |
|
|
319
|
+
| Unique root class `am-preview--{pluginName}-{slug}` | Avoid collisions in browse grid |
|
|
320
|
+
| No `<script>`, no `on*` handlers | Sanitized at catalog read + runtime |
|
|
321
|
+
| Keep under 8 KB (32 KB hard max) | Browse card preview — use `gif` for rich motion |
|
|
322
|
+
|
|
323
|
+
`poster` on GIFs is optional at runtime but **recommended** — lint emits `gif-missing-poster` as a **warning**.
|
|
324
|
+
|
|
325
|
+
---
|
|
326
|
+
|
|
327
|
+
## Browse size
|
|
328
|
+
|
|
329
|
+
Optional layout control for **picker** and **+ Add dock** browse grids only — not `@` autocomplete, chips, or Page Info. Orthogonal to `presentation`.
|
|
330
|
+
|
|
331
|
+
```yaml
|
|
332
|
+
browse:
|
|
333
|
+
size: large | medium | small # default: medium when omitted
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
| Size | Browse footprint |
|
|
337
|
+
| ---- | ---------------- |
|
|
338
|
+
| `large` | 1 per row band (full width) |
|
|
339
|
+
| `medium` | 2 per row band (default) |
|
|
340
|
+
| `small` | 4 per row band (horizontal strip or 2×2 quad beside mediums) |
|
|
341
|
+
|
|
342
|
+
### Packing (author order matters)
|
|
343
|
+
|
|
344
|
+
Within each **subCategory** (at a given folder level), AIditor packs items in **yaml order** into bands:
|
|
345
|
+
|
|
346
|
+
| Sequence | Layout |
|
|
347
|
+
| -------- | ------ |
|
|
348
|
+
| 4× `small` → 1× `medium` | One band: 2×2 small quad left, medium right |
|
|
349
|
+
| 1× `medium` → 4× `small` | One band: medium left, 2×2 quad right |
|
|
350
|
+
| 4× `small` → 2× `medium` | Small strip row, then band with 2 mediums |
|
|
351
|
+
| 4× `small` only | One small strip row |
|
|
352
|
+
|
|
353
|
+
Incomplete small quads leave empty cells (best-effort). `large` without `presentation` / `thumbnail` logs a **warning** (`browse-large-without-presentation`).
|
|
354
|
+
|
|
355
|
+
---
|
|
356
|
+
|
|
357
|
+
## Contract lookup
|
|
358
|
+
|
|
359
|
+
Use id convention **`<pluginName>:<contractName>`** (e.g. `wix-stores:product-page`).
|
|
360
|
+
|
|
361
|
+
AIditor resolves `agent-kit/materialized-contracts/<plugin>/<contract>.jay-contract` for:
|
|
362
|
+
|
|
363
|
+
- Route param helper buttons when multiple attached contracts share required params
|
|
364
|
+
- Collision warnings when multiple contracts need the same route param
|
|
365
|
+
|
|
366
|
+
Dynamic segments are edited in route fields — never as catalog item parameters.
|
|
367
|
+
|
|
368
|
+
---
|
|
369
|
+
|
|
370
|
+
## Examples
|
|
371
|
+
|
|
372
|
+
### Headless contract (reference)
|
|
94
373
|
|
|
95
374
|
```yaml
|
|
96
375
|
- id: wix-stores:product-page
|
|
@@ -104,27 +383,155 @@ Example (wix-stores): see `packages/wix-stores/lib/setup.ts` → `writeAddMenuCa
|
|
|
104
383
|
Read agent-kit/materialized-contracts/wix-stores/product-page.jay-contract.
|
|
105
384
|
```
|
|
106
385
|
|
|
107
|
-
|
|
386
|
+
### Stage-place visual effect
|
|
387
|
+
|
|
388
|
+
```yaml
|
|
389
|
+
- id: ui-kit:spring-button-hover
|
|
390
|
+
title: Spring button hover
|
|
391
|
+
category: Effects
|
|
392
|
+
subCategory: Animation
|
|
393
|
+
pluginName: ui-kit
|
|
394
|
+
presentation:
|
|
395
|
+
type: gif
|
|
396
|
+
src: thumbnails/ui-kit/spring-hover.gif
|
|
397
|
+
poster: thumbnails/ui-kit/spring-hover-poster.png
|
|
398
|
+
interaction:
|
|
399
|
+
mode: stage-place
|
|
400
|
+
stagePromptTemplate: |
|
|
401
|
+
Add spring hover effect at this location.
|
|
402
|
+
prompt: |
|
|
403
|
+
Read agent-kit/aiditor/skills/ui-kit/spring-button-hover.md and implement the effect.
|
|
404
|
+
```
|
|
405
|
+
|
|
406
|
+
### Html-fragment preview
|
|
407
|
+
|
|
408
|
+
```yaml
|
|
409
|
+
- id: ui-kit:button-demo
|
|
410
|
+
title: Button demo
|
|
411
|
+
category: Effects
|
|
412
|
+
presentation:
|
|
413
|
+
type: html-fragment
|
|
414
|
+
html: |
|
|
415
|
+
<div class="am-preview am-preview--ui-kit-button-demo">
|
|
416
|
+
<style>
|
|
417
|
+
@scope (.am-preview) {
|
|
418
|
+
.am-preview-btn { padding: 10px 18px; border-radius: 10px; background: #2563eb; color: #fff; border: none; }
|
|
419
|
+
}
|
|
420
|
+
</style>
|
|
421
|
+
<button type="button" class="am-preview-btn">Hover me</button>
|
|
422
|
+
</div>
|
|
423
|
+
prompt: |
|
|
424
|
+
…
|
|
425
|
+
```
|
|
426
|
+
|
|
427
|
+
### Generated media item
|
|
108
428
|
|
|
109
429
|
```yaml
|
|
110
430
|
- id: wix-media:hero-summer-2026
|
|
111
431
|
title: Hero — summer 2026
|
|
112
432
|
category: Media
|
|
113
433
|
pluginName: wix-media
|
|
434
|
+
folderPath:
|
|
435
|
+
- Marketing
|
|
114
436
|
prompt: |
|
|
115
437
|
URL: https://static.wixstatic.com/media/abc123~mv2.jpg
|
|
116
438
|
Media id: abc123-def-456-789
|
|
117
439
|
```
|
|
118
440
|
|
|
119
|
-
|
|
441
|
+
### Category row (@-only — excluded from browse)
|
|
442
|
+
|
|
443
|
+
```yaml
|
|
444
|
+
- id: wix-stores:category:bedroom
|
|
445
|
+
title: Bedroom
|
|
446
|
+
category: Store
|
|
447
|
+
subCategory: Categories
|
|
448
|
+
pluginName: wix-stores
|
|
449
|
+
prompt: |
|
|
450
|
+
Wix category id: abc-123. Use for product-search category filter on home page.
|
|
451
|
+
```
|
|
452
|
+
|
|
453
|
+
---
|
|
454
|
+
|
|
455
|
+
## Validation
|
|
456
|
+
|
|
457
|
+
All rules below are enforced by **`jay-stack validate-plugin`** when the plugin ships add-menu yaml. Each finding includes a **code**, **location**, and **suggestion** pointing back to this guide.
|
|
458
|
+
|
|
459
|
+
Warnings do not fail validation unless `--strict`.
|
|
460
|
+
|
|
461
|
+
### Schema errors
|
|
462
|
+
|
|
463
|
+
| Code | When |
|
|
464
|
+
| ---- | ---- |
|
|
465
|
+
| `missing-id` / `missing-title` / `missing-category` / `missing-prompt` | Required string missing or empty |
|
|
466
|
+
| `rejected-field-kind` | `kind` field present |
|
|
467
|
+
| `rejected-field-parameters` | `parameters` field present |
|
|
468
|
+
| `rejected-field-component` | `component` field present |
|
|
469
|
+
| `rejected-field-allowedScopes` | `allowedScopes` field present |
|
|
470
|
+
| `interaction-invalid-mode` | `interaction.mode` not reference / stage-place |
|
|
471
|
+
| `presentation-missing-src` | `image` or `gif` without `src` |
|
|
472
|
+
| `html-fragment-src-not-allowed` | `html-fragment` with `presentation.src` |
|
|
473
|
+
| `html-fragment-missing-html` | `html-fragment` with missing or empty `html` |
|
|
474
|
+
| `html-fragment-unsafe-markup` | `<script>`, event handlers, `javascript:` URLs |
|
|
475
|
+
| `html-fragment-oversize-hard` | sanitized html > 32 KB |
|
|
476
|
+
| `browse-unknown-size` | `browse.size` not large / medium / small |
|
|
477
|
+
| `folder-path-not-array` | `folderPath` is not a string array |
|
|
478
|
+
| `folder-path-segment-type` | non-string segment |
|
|
479
|
+
| `folder-path-empty-segment` | empty segment string |
|
|
480
|
+
| `folder-path-invalid-segment` | `..`, `/`, or `\` in segment |
|
|
481
|
+
| `folder-path-adjacent-duplicate` | duplicate consecutive segments |
|
|
482
|
+
| `folder-path-too-deep` | more than 32 segments |
|
|
483
|
+
| `catalog-yaml-parse-error` | invalid yaml syntax |
|
|
484
|
+
| `catalog-not-object` / `catalog-items-not-array` | malformed file root |
|
|
485
|
+
|
|
486
|
+
### Lint warnings and errors
|
|
487
|
+
|
|
488
|
+
| Code | Severity | When |
|
|
489
|
+
| ---- | -------- | ---- |
|
|
490
|
+
| `gif-missing-poster` | warning | `presentation.type: gif` without `poster` |
|
|
491
|
+
| `html-fragment-missing-root-div` | warning | html does not have a single root `<div>` |
|
|
492
|
+
| `html-fragment-missing-at-scope` | warning | no `<style>` with `@scope` on root class |
|
|
493
|
+
| `html-fragment-oversize-soft` | warning | sanitized html > 8 KB |
|
|
494
|
+
| `browse-large-without-presentation` | warning | `browse.size: large` without presentation or thumbnail |
|
|
495
|
+
| `add-menu-missing-agentkit-handler` | warning | catalog template in package but no `agentkit` in `plugin.yaml` |
|
|
496
|
+
| `add-menu-legacy-setup-handler` | warning | `setup` handler source writes `agent-kit/aiditor/add-menu` — move to `agentkit` |
|
|
497
|
+
|
|
498
|
+
### Where validation runs
|
|
499
|
+
|
|
500
|
+
| When | How |
|
|
501
|
+
| ---- | --- |
|
|
502
|
+
| **Plugin CI / local dev** | `jay-stack validate-plugin` (or `yarn validate` in package) |
|
|
503
|
+
| **AIditor runtime** | Same rules when loading `agent-kit/aiditor/add-menu/*.yaml` — invalid items are skipped with warnings |
|
|
504
|
+
|
|
505
|
+
---
|
|
506
|
+
|
|
507
|
+
## Dev workflow
|
|
508
|
+
|
|
509
|
+
Catalog files are read when you **open + Add** or the Add Menu picker, or click **Refresh catalog**.
|
|
510
|
+
|
|
511
|
+
| You changed… | Do this |
|
|
512
|
+
| ------------ | ------- |
|
|
513
|
+
| Project yaml under `agent-kit/aiditor/add-menu/` | **Refresh catalog** in + Add / picker, or close and reopen |
|
|
514
|
+
| Package **template** in your plugin repo | `yarn agent-kit` (or `jay-stack agent-kit`), then Refresh in AIditor |
|
|
515
|
+
| Thumbnails or GIFs in package | Re-run agent-kit (copies to `agent-kit/aiditor/` and `public/aiditor-add-menu-thumbnails/`), then Refresh |
|
|
516
|
+
|
|
517
|
+
There is **no** automatic file-watch refresh.
|
|
518
|
+
|
|
519
|
+
---
|
|
520
|
+
|
|
521
|
+
## Verification checklist
|
|
522
|
+
|
|
523
|
+
1. `plugin.yaml` declares `agentkit` → agent-kit handler
|
|
524
|
+
2. `yarn agent-kit` — yaml + thumbnails under `agent-kit/aiditor/`
|
|
525
|
+
3. `jay-stack validate-plugin` — add-menu schema and lint clean (use `--strict` in CI)
|
|
526
|
+
4. Plugin listed in project `package.json` (or `src/plugins/` for local dev)
|
|
527
|
+
5. AIditor → **+ Add** / Add Menu — items under your `category`
|
|
528
|
+
6. Attach item → submit → agent prompt contains your `prompt` block
|
|
529
|
+
7. `jay-stack validate` on pages the agent creates
|
|
120
530
|
|
|
121
|
-
|
|
531
|
+
---
|
|
122
532
|
|
|
123
|
-
##
|
|
533
|
+
## Philosophy (short)
|
|
124
534
|
|
|
125
|
-
|
|
126
|
-
2. Ensure plugin is in `package.json`
|
|
127
|
-
3. Open AIditor → Add Page → **+ Add** — items appear under your `category`
|
|
128
|
-
4. Run `jay-stack validate` on pages the agent creates
|
|
535
|
+
> Plugins extend AIditor by contributing catalog items. Each item is a prepared agent context block. The user attaches context through two surfaces: **place on stage** when location matters (`stage-place`); **`@` reference** when scope matters (`reference`, default).
|
|
129
536
|
|
|
130
|
-
For
|
|
537
|
+
For generic plugin development, read `agent-kit/plugin/INSTRUCTIONS.md` and `agent-kit/plugin/setup-guide.md`.
|