-
-
+
+
Agent fetches
@@ -252,9 +275,24 @@ function host(url: string): string {
class="p-card p-component rounded-lg p-3 flex items-start gap-3"
>
-
-
-
+
+
+
@@ -268,11 +306,22 @@ function host(url: string): string {
:class="ev.status < 400 ? 'bg-success/10 text-success' : 'bg-danger/10 text-danger'"
>{{ ev.status }}
-
{{ ev.url }}
-
+ {{ ev.url }}
+
{{ ev.error }}
-
+
{{ ev.snippet }}
@@ -284,7 +333,11 @@ function host(url: string): string {
v-else-if="!answer && !error && !loading"
class="mt-10 flex flex-col items-center justify-center text-center text-surface-400 gap-2"
>
-
+
Enter a URL or question — watch the agent fetch pages, then get the answer.
diff --git a/frontend/applications/main/src/pages/users.vue b/frontend/applications/main/src/pages/users.vue
index 4298a7b..7d5be2c 100644
--- a/frontend/applications/main/src/pages/users.vue
+++ b/frontend/applications/main/src/pages/users.vue
@@ -174,13 +174,7 @@ async function confirmDelete(user: User) {
const name = user.full_name || user.email
const confirmed = await host.confirm({
header: 'Delete User',
- html: `
-
-
-
Delete "${name}"?
-
This will permanently delete the user and revoke all access. This action cannot be undone.
-
-
`,
+ message: `Delete "${name}"? This will permanently delete the user and revoke all access. This action cannot be undone.`,
acceptLabel: 'Delete',
rejectLabel: 'Cancel',
acceptProps: { severity: 'danger' },
diff --git a/frontend/applications/main/src/router/index.ts b/frontend/applications/main/src/router/index.ts
index 9e56703..f45338c 100644
--- a/frontend/applications/main/src/router/index.ts
+++ b/frontend/applications/main/src/router/index.ts
@@ -1,12 +1,7 @@
-import type { HostApi } from '../types'
+import type { HostApi, ProxyApiInstance } from '../types'
import type { Router } from 'vue-router'
import { createAppRouter as createAppRouterFactory } from '@wippy-fe/router'
-type OnSubscription = (
- pattern: string,
- callback: (event: { path?: string, message?: unknown }) => void,
-) => void
-
const routes = [
{
path: '/',
@@ -28,14 +23,15 @@ const routes = [
name: 'research',
component: () => import('../pages/research.vue'),
},
- // Former standalone demo pages now live as tabs on /components.
{
path: '/iframe-demo',
- redirect: { name: 'components', query: { tab: 'iframe' } },
+ name: 'iframe-demo',
+ component: () => import('../pages/iframe-demo.vue'),
},
{
path: '/nested-nav/:part(.*)*',
- redirect: { name: 'components', query: { tab: 'nested' } },
+ name: 'nested-nav',
+ component: () => import('../pages/nested-nav.vue'),
},
{
path: '/:pathMatch(.*)*',
@@ -51,7 +47,7 @@ const routes = [
* - afterEach → host.onRouteChanged
* - @history subscription → parent → child URL mirroring
*/
-export function createAppRouter(host: HostApi, on: OnSubscription | null, initialPath: string): Router {
+export function createAppRouter(host: HostApi, on: ProxyApiInstance['on'] | null, initialPath: string): Router {
return createAppRouterFactory(routes, {
host: host as never,
on: on as never,
diff --git a/frontend/applications/main/tsconfig.tsbuildinfo b/frontend/applications/main/tsconfig.tsbuildinfo
index a82be0b..98fd214 100644
--- a/frontend/applications/main/tsconfig.tsbuildinfo
+++ b/frontend/applications/main/tsconfig.tsbuildinfo
@@ -1 +1 @@
-{"root":["./src/app.ts","./src/constants.ts","./src/types.ts","./src/composables/usewippy.ts","./src/router/index.ts","./src/stores/users.ts","./src/app/app.vue","./src/pages/components.vue","./src/pages/home.vue","./src/pages/users.vue","./vite.config.ts"],"errors":true,"version":"5.9.3"}
\ No newline at end of file
+{"root":["./src/app.ts","./src/constants.ts","./src/types.ts","./src/composables/usewippy.ts","./src/router/index.ts","./src/stores/users.ts","./src/app/app.vue","./src/pages/components.vue","./src/pages/home.vue","./src/pages/iframe-demo.vue","./src/pages/nested-nav.vue","./src/pages/research.vue","./src/pages/users.vue","./vite.config.ts"],"version":"5.9.3"}
\ No newline at end of file
diff --git a/frontend/docs/README.md b/frontend/docs/README.md
index 1ac7969..bce0c53 100644
--- a/frontend/docs/README.md
+++ b/frontend/docs/README.md
@@ -45,6 +45,7 @@ Full proxy API type definitions ship with the `@wippy-fe/proxy` npm package at `
| [web-component-loading.md](web-component-loading.md) | How the host autoloads `view.component` entries: registration → API filter → script injection → `define()` chain, the `@wippy-fe/proxy` eager-getter contract (root cause of `Proxy globals not found`), externals + pinia gotcha, web-host version floor, diagnostic recipe | Tag silently renders as unknown, `customElements.get` returns undefined, `Proxy globals not found`, `process is not defined` in a WC bundle |
| [app-guide.md](app-guide.md) | Web app development: routing, Vite config, `window.$W` proxy, Vue Router, layouts | Building a web app |
| [app-checklist.md](app-checklist.md) | Pre-submission checklist for web apps | Before submitting a web app |
+| [agent-artifacts.md](agent-artifacts.md) | CreateArtifact tool: three content modes, display modes, embed token rule, inline component shortcut, SPA page sizing | Writing or debugging an agent trait that creates artifacts |
| [fe-compliance-checklist.md](fe-compliance-checklist.md) | Exhaustive compliance checklist for `view.page` and `view.component` modules. **AI auditors:** start at **Appendix D — AI Audit Playbook** for the phase order, swarm decision matrix, and moderator output schema. | Auditing a module before merge; AI-driven review of a PR |
### Reference
diff --git a/frontend/docs/agent-artifacts.md b/frontend/docs/agent-artifacts.md
new file mode 100644
index 0000000..8b93e10
--- /dev/null
+++ b/frontend/docs/agent-artifacts.md
@@ -0,0 +1,147 @@
+# Agent artifacts: CreateArtifact tool guide
+
+How the `CreateArtifact` tool works, how artifact embed tokens differ from inline component tags, and how to handle SPA page sizing. Read this if you are writing or debugging an agent trait that creates artifacts, or if an agent is producing broken `
` tags in its replies.
+
+---
+
+## Three content modes
+
+### 1. Text mode — LLM-generated content
+
+Pass `title` + `content` + `content_type` (`text/markdown` or `text/html`).
+
+```json
+{
+ "title": "Fruits table",
+ "content": "| Fruit | Color |\n|-------|-------|\n| Apple | Red |",
+ "content_type": "text/markdown"
+}
+```
+
+Use for formatted text, tables, code samples, documentation, or generated HTML/JS apps.
+
+### 2. Component tag mode — auto-registered components
+
+Pass `title` + `tag_name` + `props`. Only use tag names listed in the **Auto-registered components** section of the agent's compiled catalog (populated by `build_artifacts_catalog.lua` at compile time).
+
+```json
+{
+ "title": "Reaction bar",
+ "tag_name": "example-reaction-bar",
+ "props": { "items": ["👍", "❤️", "🎉"] }
+}
+```
+
+Do **not** set `content_type` in this mode.
+
+### 3. Package mode — ESM components or SPA pages
+
+Pass `title` + `content_type="application/json"` + `content` = the full package JSON copied verbatim from the catalog.
+
+```json
+{
+ "title": "Admin Panel",
+ "content_type": "application/json",
+ "content": "{\"wippy\":{\"type\":\"page\",\"path\":\"index.html\",\"proxy\":{\"enabled\":true}},\"name\":\"main\",\"version\":\"1.0.0\",\"specification\":\"wippy-component-1.0\",\"title\":\"Admin Panel\",\"baseUrl\":\"http://localhost:8086/app/\"}"
+}
+```
+
+Copy the package JSON verbatim from the catalog — do **not** construct or guess field values.
+
+---
+
+## Display modes (`instructions` parameter)
+
+### `instructions: false` (default)
+
+Artifact appears as a standalone card in the chat thread. The agent reply is plain prose — do **not** embed any tag in reply text. Use when the artifact IS the main answer.
+
+### `instructions: true`
+
+The tool result returns an opaque embed token. The agent MUST paste this token verbatim into its reply at the exact position where the artifact should appear inline. Use when the artifact is a supporting detail within flowing prose.
+
+**The token comes exclusively from the tool result** — it is never constructed by the agent. If the agent has not just called `CreateArtifact` with `instructions=true`, there is no token to paste.
+
+---
+
+## Artifact embed token rule — ABSOLUTE
+
+**Never write an artifact embed tag in reply text under any circumstances** unless you are pasting the exact string the `CreateArtifact` tool just returned with `instructions=true`.
+
+- Not as a placeholder
+- Not as an example
+- Not in any other context
+
+If you write the tag yourself with a made-up or guessed ID, the host will attempt to fetch that artifact from the API and display an error (or fire repeated 404 requests for invalid IDs). The only valid artifact embed in a reply is a token the tool gave you.
+
+When explaining the embed mechanism in prose, describe it in words — do not type the tag.
+
+---
+
+## Inline component shortcut — no CreateArtifact needed
+
+For **auto-registered** components, the agent may write the component's tag name directly in reply text as raw HTML:
+
+```
+Here is a reaction bar:
+```
+
+This works because auto-registered components are globally defined custom elements in the host page — writing the tag is equivalent to placing the element in the DOM.
+
+**This is completely different from an artifact embed token:**
+
+| | Inline component tag | Artifact embed token |
+|---|---|---|
+| Written by | Agent (directly in reply) | Pasted from tool result only |
+| Requires CreateArtifact | No | Yes (`instructions=true`) |
+| Persists in history | No | Yes |
+| Valid tag names | Auto-registered catalog only | N/A — opaque token |
+
+Use the inline shortcut only for tags listed in the **Auto-registered components** catalog. `artifact` is NOT one of these tags — never write it inline.
+
+---
+
+## SPA page sizing
+
+Pages in the catalog carry a `Sizing` label:
+
+### `sizing: auto`
+
+The page has `wippy.proxy.injections.resizeObserver: true` in its package JSON. It sends its intrinsic height to the host via `CmdBodySize` messages, so it renders correctly in any context (standalone full-panel or inline artifact). Copy the package JSON verbatim.
+
+### `sizing: fixed`
+
+The page does **not** report its height. It renders correctly only in a full-panel (standalone) artifact context. If embedded inline in a `sizing="content"` context it starts at zero height and stays blank.
+
+**If the user explicitly needs a `sizing: fixed` page embedded inline**, patch the package JSON before passing it as `content`:
+
+```
+Original: "proxy": {"enabled": true}
+Patched: "proxy": {"enabled": true, "injections": {"resizeObserver": true}}
+```
+
+Only apply this patch when inline embedding is explicitly required. For standalone display, copy the JSON verbatim.
+
+---
+
+## Catalog source
+
+The available components and pages catalog is built at agent compile time by `src/app/agents/build_artifacts_catalog.lua`. It reads:
+- `wippy.views:component_registry` — auto-registered and ESM components
+- `wippy.views:page_registry` — SPA pages
+- `wippy.views:bundled_meta` — metadata from `wippy-meta.json`
+
+The catalog is appended to the agent's system prompt via `build_func_id: app.agents:build_artifacts_catalog` on the `wippy_artifacts_trait`.
+
+---
+
+## Debug endpoint
+
+To inspect the compiled system prompt (including the full artifact catalog):
+
+```
+GET /api/public/debug/agent-prompt?agent=app.agents:wippy
+x-auth-token:
+```
+
+Returns JSON with `system_prompt`, `tools`, `model`, and `prompt_length`.
diff --git a/frontend/docs/theming.md b/frontend/docs/theming.md
index 0318aa5..46d26bb 100644
--- a/frontend/docs/theming.md
+++ b/frontend/docs/theming.md
@@ -146,6 +146,42 @@ Mismatched placement is the #1 source of theme drift. The bundle's `.css` ships
The compliance checklist enforces this at REJECT severity (REJECT 42b for `:root { --p-* }` in child `.css`, REJECT 43a for raw `.p-*` selectors in child `.css`).
+### The theming rule — non-optional. Read first, follow vigorously.
+
+**Apply this rule before writing the first selector in any Wippy frontend module.** It governs every FE component you ship.
+
+Wippy supports two micro-frontend embedding technologies:
+
+- **Page apps in iframes** (e.g. `chat`, `automations`, an admin module loaded via `