@gxp-dev/tools 2.0.83 → 2.0.85

package/README.md

@@ -93,12 +93,13 @@ It does **not** overwrite your source files (`src/`, `theme-layouts/`, etc.).
 - **Config linting** — AJV-based JSON Schema validation of `configuration.json` (form-builder definitions) and `app-manifest.json` (plugin metadata + defaults).
 - **Pre-commit hook** — `.githooks/pre-commit` runs Prettier, ESLint, and the GxP linter on staged files; configured automatically via the `prepare` npm script.
 - **Unit testing** — Vitest + `@vue/test-utils` wired out of the box; scaffolded tests via the MCP server.
-- **MCP server** — 33 tools for AI coding assistants (see below).
+- **MCP server** — 32 tools for AI coding assistants (see below). UIKit component/story tools are served by the uikit's own Storybook MCP, auto-registered when you run `gxdev storybook`.
 - **AI scaffolding** — pre-wired configs for Claude Code, Codex, and Gemini during `init`.
+- **Experience-flow demo** — `template/src/DemoExperience.vue` is an annotated kiosk flow built with `@gxp-dev/uikit`'s state-machine orchestrator: branching paths, default + inline actions, `callApi` adapter, slot overrides, and a live state inspector. Linked from `DemoPage.vue`.
 
 ## MCP Server for AI assistants
 
-The toolkit ships `mcp-serve` (bin `@gxp-dev/tools/mcp/mcp-serve.js`), an MCP server exposing 33 tools across seven families. It speaks MCP over stdio via the official `@modelcontextprotocol/sdk` `StdioServerTransport`. Point your AI assistant at it to get API-aware, schema-aware, test-aware help inside plugin projects:
+The toolkit ships `mcp-serve` (bin `@gxp-dev/tools/mcp/mcp-serve.js`), an MCP server exposing 32 tools across six families. It speaks MCP over stdio via the official `@modelcontextprotocol/sdk` `StdioServerTransport`. Point your AI assistant at it to get API-aware, schema-aware, test-aware help inside plugin projects:
 
 | Family                 | Tools                                                                                                                                                                                                                                                                                               |
 | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -108,7 +109,8 @@ The toolkit ships `mcp-serve` (bin `@gxp-dev/tools/mcp/mcp-serve.js`), an MCP se
 | **Docs search** (3)    | `docs_list_pages`, `docs_search`, `docs_get_page` — full-text across `docs.gxp.dev` via its sitemap                                                                                                                                                                                                 |
 | **Test helpers** (2)   | `test_scaffold_component_test`, `test_api_route`                                                                                                                                                                                                                                                    |
 | **Data models** (1)    | `describe_data_models` — enumerate or detail OpenAPI `components.schemas` with $ref + allOf flattening                                                                                                                                                                                              |
-| **UIKit** (1)          | `list_uikit_components` — list components exported by `@gxp-dev/uikit` installed in the current project                                                                                                                                                                                             |
+
+UIKit component introspection (and story preview/run-tests) is served by the uikit itself via `@storybook/addon-mcp`. Run `gxdev storybook` from a plugin project and the addon exposes an HTTP MCP server at `http://localhost:6006/mcp` — `template/mcp.json` registers it as `gxp-uikit-storybook` alongside `gxp-api`, so AI assistants pick it up automatically when storybook is running.
 
 The previous bin name `gxp-api-server` still ships as a deprecation shim — it prints a stderr notice and forwards to the same server. Update your `.mcp.json` / `.gemini/settings.json` to use `mcp-serve` going forward.
 
@@ -121,8 +123,9 @@ After `gxdev init`:
 ```
 my-plugin/
 ├── src/
-│   ├── Plugin.vue              # App entry point
-│   ├── DemoPage.vue            # Example component
+│   ├── Plugin.vue              # App entry point + lightweight in-app routing
+│   ├── DemoPage.vue            # Example component (gxp-* directives, sockets, store)
+│   ├── DemoExperience.vue      # Annotated kiosk flow using @gxp-dev/uikit experience-flow
 │   ├── public/                 # Static assets (served at /src/public/*)
 │   └── stores/
 │       └── index.js            # Pinia store setup

package/bin/lib/cli.js

@@ -25,6 +25,7 @@ const {
 	extractConfigCommand,
 	addDependencyCommand,
 	lintCommand,
+	storybookCommand,
 } = require("./commands")
 
 // Load global configuration
@@ -350,6 +351,19 @@ const cli = yargs
 		},
 		lintCommand,
 	)
+	.command(
+		"storybook",
+		"Run @gxp-dev/uikit Storybook from this project (port 6006)",
+		{
+			build: {
+				describe:
+					"Build a static Storybook bundle instead of starting the dev server",
+				type: "boolean",
+				default: false,
+			},
+		},
+		storybookCommand,
+	)
 	.command(
 		"add-dependency",
 		"Add an API dependency to app-manifest.json via interactive wizard",

package/bin/lib/commands/index.js

@@ -21,6 +21,7 @@ const {
 const { extractConfigCommand } = require("./extract-config")
 const { addDependencyCommand } = require("./add-dependency")
 const { lintCommand } = require("./lint")
+const { storybookCommand } = require("./storybook")
 
 module.exports = {
 	initCommand,
@@ -38,4 +39,5 @@ module.exports = {
 	extractConfigCommand,
 	addDependencyCommand,
 	lintCommand,
+	storybookCommand,
 }

package/bin/lib/commands/storybook.js

@@ -0,0 +1,131 @@
+/**
+ * Storybook Command
+ *
+ * Runs the @gxp-dev/uikit Storybook instance from the plugin project. The
+ * uikit ships its own storybook config + @storybook/addon-mcp but declares
+ * the storybook ecosystem as *optional* peerDependencies, so plugin projects
+ * stay lean by default. This command resolves the installed uikit, detects
+ * any missing storybook peers, prompts to install them in the plugin
+ * project's node_modules, then delegates to the uikit's storybook script.
+ *
+ * When `storybook dev` is running, the addon-mcp also exposes an HTTP MCP
+ * server at http://localhost:6006/mcp — the template's mcp.json registers it
+ * as a second MCP server alongside the toolkit's stdio one.
+ */
+
+const path = require("path")
+const fs = require("fs")
+const shell = require("shelljs")
+const readline = require("readline")
+const { findProjectRoot } = require("../utils")
+const { resolveUikit } = require("../utils/uikit")
+
+const STORYBOOK_PEERS = [
+	"storybook",
+	"@storybook/vue3-vite",
+	"@storybook/addon-mcp",
+	"@storybook/addon-a11y",
+	"@storybook/addon-themes",
+]
+
+function isInstalled(pkgName, fromDir) {
+	let dir = path.resolve(fromDir)
+	while (dir) {
+		const candidate = path.join(dir, "node_modules", pkgName, "package.json")
+		if (fs.existsSync(candidate)) return true
+		const parent = path.dirname(dir)
+		if (parent === dir) break
+		dir = parent
+	}
+	return false
+}
+
+function findMissingPeers(uikitRoot, pkg) {
+	const peerSpecs = (pkg && pkg.peerDependencies) || {}
+	return STORYBOOK_PEERS.filter((name) => {
+		if (!peerSpecs[name]) return false
+		return !isInstalled(name, uikitRoot)
+	}).map((name) => `${name}@${peerSpecs[name]}`)
+}
+
+async function confirm(question) {
+	return new Promise((resolve) => {
+		const rl = readline.createInterface({
+			input: process.stdin,
+			output: process.stdout,
+		})
+		rl.question(`${question} (Y/n) `, (answer) => {
+			rl.close()
+			const trimmed = (answer || "").trim().toLowerCase()
+			resolve(trimmed === "" || trimmed === "y" || trimmed === "yes")
+		})
+	})
+}
+
+async function storybookCommand(argv) {
+	const resolved = resolveUikit(process.cwd())
+	if (!resolved) {
+		console.error(
+			"❌ Could not find @gxp-dev/uikit in this project's node_modules.",
+		)
+		console.log("💡 Install it with: npm install @gxp-dev/uikit")
+		process.exit(1)
+	}
+
+	const { root: uikitRoot, pkg } = resolved
+	const wantsBuild = Boolean(argv.build)
+	const scriptName = wantsBuild ? "storybook:build" : "storybook"
+	const script = pkg.scripts && pkg.scripts[scriptName]
+	const storybookConfig = path.join(uikitRoot, ".storybook")
+
+	if (!script || !fs.existsSync(storybookConfig)) {
+		console.error(
+			`❌ @gxp-dev/uikit@${pkg.version || "?"} at ${uikitRoot} does not ship a Storybook setup.`,
+		)
+		console.log(
+			"💡 Upgrade the uikit to a version whose `files` field includes `.storybook` and `src`.",
+		)
+		process.exit(1)
+	}
+
+	const missing = findMissingPeers(uikitRoot, pkg)
+	if (missing.length > 0) {
+		console.log("📦 Storybook tooling is not installed yet.")
+		console.log("   The uikit lists these as optional peerDependencies:")
+		for (const spec of missing) {
+			console.log(`   • ${spec}`)
+		}
+		const proceed = await confirm(
+			"   Install them now in this project (npm install --save-dev)?",
+		)
+		if (!proceed) {
+			console.log(
+				"⏭  Skipped. Install manually and re-run: npm install --save-dev " +
+					missing.join(" "),
+			)
+			process.exit(1)
+		}
+
+		const projectRoot = findProjectRoot()
+		const installCmd = `npm install --save-dev --no-fund --no-audit ${missing.map((m) => `"${m}"`).join(" ")}`
+		console.log(`▶ ${installCmd}`)
+		const installResult = shell.exec(installCmd, { cwd: projectRoot })
+		if (installResult.code !== 0) {
+			console.error("❌ Install failed. Resolve the errors and try again.")
+			process.exit(installResult.code)
+		}
+	}
+
+	const label = wantsBuild
+		? "📚 Building Storybook from @gxp-dev/uikit..."
+		: "📚 Starting Storybook from @gxp-dev/uikit (http://localhost:6006)"
+	console.log(label)
+	console.log(`📁 UIKit path: ${uikitRoot}`)
+
+	const result = shell.exec(`npm run ${scriptName}`, { cwd: uikitRoot })
+	if (result.code !== 0) {
+		process.exit(result.code)
+	}
+}
+
+module.exports = { storybookCommand }

package/bin/lib/constants.js

@@ -48,6 +48,8 @@ const DEFAULT_SCRIPTS = {
 	"datastore:add": "gxdev datastore add",
 	"datastore:scan": "gxdev datastore scan-strings",
 	"datastore:config": "gxdev datastore config",
+	storybook: "gxdev storybook",
+	"storybook:build": "gxdev storybook --build",
 }
 
 // Default ports

package/bin/lib/utils/ai-scaffold.js

@@ -997,7 +997,7 @@ function buildInteractiveInitialPrompt(projectName, description, provider) {
 		"- **Docs search** — `docs_search`, `docs_get_page`, `docs_list_pages` (full-text search across docs.gxp.dev).",
 		"- **Test helpers** — `test_scaffold_component_test`, `test_api_route`.",
 		"- **Data models** — `describe_data_models` (enumerate or detail OpenAPI components.schemas; walks allOf and resolves $ref by name).",
-		"- **UIKit** — `list_uikit_components` (list components exported by `@gxp-dev/uikit` installed in this project).",
+		"- **UIKit (via Storybook MCP)** — when `npm run storybook` is running, the uikit's `@storybook/addon-mcp` exposes `preview-stories`, `get-storybook-story-instructions`, `get-documentation`, `list-all-documentation`, and `run-story-tests` at http://localhost:6006/mcp (registered in mcp.json as `gxp-uikit-storybook`). Use these to discover available components and stories.",
 		"",
 		"Follow the full workflow from the instructions: (1) understand the feature, (2) discover data sources via MCP, (3) plan including the admin configuration form, (4) implement, (5) **sync the manifest and build the admin form**, (6) test with real broadcasts, (7) final `gxdev lint --all`.",
 		"",

package/bin/lib/utils/index.js

@@ -11,6 +11,7 @@ const prompts = require("./prompts")
 const aiScaffold = require("./ai-scaffold")
 const extractConfig = require("./extract-config")
 const versionCheck = require("./version-check")
+const uikit = require("./uikit")
 
 module.exports = {
 	...paths,
@@ -20,4 +21,5 @@ module.exports = {
 	...aiScaffold,
 	...extractConfig,
 	...versionCheck,
+	...uikit,
 }

package/bin/lib/utils/uikit.js

@@ -0,0 +1,40 @@
+/**
+ * UIKit resolution helpers.
+ *
+ * Resolves `@gxp-dev/uikit` from a plugin project's node_modules by walking
+ * up the directory tree (works with npm, pnpm, yarn workspaces). We mimic the
+ * walk-up rather than calling require.resolve("@gxp-dev/uikit/...") because
+ * the uikit's package.json declares a strict `exports` field with only
+ * `import` + `types` conditions; from a CJS context require.resolve fails
+ * against that exports map even though the directory exists on disk.
+ */
+
+const fs = require("fs")
+const path = require("path")
+
+/**
+ * @returns {{ root: string, pkg: object } | null}
+ */
+function resolveUikit(cwd = process.cwd()) {
+	let dir = path.resolve(cwd)
+	while (dir) {
+		const candidate = path.join(dir, "node_modules", "@gxp-dev", "uikit")
+		const pkgPath = path.join(candidate, "package.json")
+		if (fs.existsSync(pkgPath)) {
+			try {
+				const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"))
+				if (pkg && pkg.name === "@gxp-dev/uikit") {
+					return { root: candidate, pkg }
+				}
+			} catch {
+				// malformed package.json — keep walking
+			}
+		}
+		const parent = path.dirname(dir)
+		if (parent === dir) break
+		dir = parent
+	}
+	return null
+}
+
+module.exports = { resolveUikit }

package/mcp/lib/server.js

@@ -13,7 +13,12 @@
  *   - Docs tools         (docs-tools.js)
  *   - Test tools         (test-tools.js)
  *   - Model tools        (model-tools.js)
- *   - UIKit tools        (uikit-tools.js)
+ *
+ * UIKit component introspection has moved out of this server. The uikit
+ * ships @storybook/addon-mcp; when developers run `gxdev storybook` the
+ * uikit's Storybook exposes its own HTTP MCP server at
+ * http://localhost:6006/mcp, registered as `gxp-uikit-storybook` in the
+ * plugin project's mcp.json.
  */
 
 const { fetchSpec, getEnvironment, getEnvUrls } = require("./specs")
@@ -34,11 +39,6 @@ const {
 	handleModelToolCall,
 	isModelTool,
 } = require("./model-tools")
-const {
-	UIKIT_TOOLS,
-	handleUikitToolCall,
-	isUikitTool,
-} = require("./uikit-tools")
 
 const SERVER_INFO = {
 	name: "gxp-mcp-serve",
@@ -46,7 +46,7 @@ const SERVER_INFO = {
 }
 
 const SERVER_DESCRIPTION =
-	"GxP toolkit MCP server: API specs, data models, UIKit components, config/manifest editing, documentation search, and plugin test helpers for AI coding assistants."
+	"GxP toolkit MCP server: API specs, data models, config/manifest editing, documentation search, and plugin test helpers for AI coding assistants. UIKit component/story tools are served by the uikit's own Storybook MCP (gxdev storybook)."
 
 /* -------------------- API spec search helpers (in-file) ------------------- */
 
@@ -247,7 +247,6 @@ const TOOLS = [
 	...DOCS_TOOLS,
 	...TEST_TOOLS,
 	...MODEL_TOOLS,
-	...UIKIT_TOOLS,
 ]
 
 /* ------------------------------ tool dispatch ----------------------------- */
@@ -258,7 +257,6 @@ async function handleToolCall(name, args = {}) {
 	if (isDocsTool(name)) return handleDocsToolCall(name, args)
 	if (isTestTool(name)) return handleTestToolCall(name, args)
 	if (isModelTool(name)) return handleModelToolCall(name, args)
-	if (isUikitTool(name)) return handleUikitToolCall(name, args)
 
 	switch (name) {
 		case "get_openapi_spec": {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@gxp-dev/tools",
-	"version": "2.0.83",
+	"version": "2.0.85",
 	"description": "Dev tools to create platform plugins",
 	"type": "commonjs",
 	"publishConfig": {
@@ -58,11 +58,13 @@
 	"dependencies": {
 		"@faker-js/faker": "^9.9.0",
 		"@fal-works/esbuild-plugin-global-externals": "^2.1.2",
+		"@gxp-dev/uikit": "^0.1.0",
 		"@modelcontextprotocol/sdk": "^1.29.0",
 		"@vitejs/plugin-vue": "^6.0.6",
 		"adm-zip": "^0.5.17",
 		"ajv": "^8.18.0",
 		"ajv-formats": "^3.0.1",
+		"axios": "^1.16.0",
 		"chrome-launcher": "^1.2.1",
 		"concurrently": "^9.2.1",
 		"cors": "^2.8.6",

package/template/mcp.json

@@ -3,6 +3,10 @@
 		"gxp-api": {
 			"command": "mcp-serve",
 			"args": []
+		},
+		"gxp-uikit-storybook": {
+			"type": "http",
+			"url": "http://localhost:6006/mcp"
 		}
 	}
 }

package/template/src/DemoExperience.vue

@@ -0,0 +1,660 @@
+<!--
+  DemoExperience.vue — A teaching demo for @gxp-dev/uikit's experience-flow system.
+
+  WHAT IT IS
+  ──────────
+  A state-machine orchestrator + a set of prebuilt page components for building
+  multi-stage interactive apps (kiosks, photo booths, AI flows, check-ins).
+
+  The whole flow below is driven by ONE configuration object passed to
+  `useExperience`. Pages emit data; the flow stores it in a reactive `context`;
+  optional `action`s run between pages to call APIs or do work.
+
+  WHAT THIS DEMO SHOWS
+  ────────────────────
+  1. `useExperience({ pages, … })`   — the orchestrator composable
+  2. `useExperienceApi({ callApi })` — adapter that maps named ops to `callApi`
+  3. `<ExperienceFlow :flow />`      — renderer with built-in loading / error UI
+  4. Prebuilt pages (Welcome, Terms, Options, Camera, CameraReview, Drawing,
+     Notepad, Loading, Final) with their default slots overridden
+  5. Branching paths via `when: (ctx) => …`
+  6. Async actions in three forms: named, inline function, and disabled
+  7. Live state side-panel — current page, busy/error refs, context dump
+  8. Reset, replay, jump-to-page controls — to make the state model visible
+
+  PRODUCTION USE
+  ──────────────
+  In a real plugin, `callApi` comes from `gxpStore.callApi(operationId, perm, data)`.
+  The uikit's adapter expects `(endpoint, payload) => Promise<T>` shape — we
+  bridge that below with a tiny lambda. Replace the mock endpoints with your
+  real operationIds and you're done.
+-->
+
+<template>
+	<div class="demo-experience-page">
+		<!-- Side panel with live flow state — great for understanding what's happening -->
+		<aside class="state-panel">
+			<header class="state-panel__header">
+				<button class="back-link" @click="$emit('navigate', 'home')">
+					← Back to Demo
+				</button>
+				<h2>Live Flow State</h2>
+			</header>
+
+			<section class="state-panel__section">
+				<h3>Current page</h3>
+				<code class="state-panel__value">{{ flow.pageName.value ?? "—" }}</code>
+				<div class="state-panel__meta">
+					index {{ flow.index.value }} / {{ flow.pages.value.length - 1 }} ·
+					<span :class="{ pill: true, 'pill--on': flow.busy.value }">
+						busy: {{ flow.busy.value }}
+					</span>
+					·
+					<span :class="{ pill: true, 'pill--err': flow.error.value }">
+						error: {{ flow.error.value?.message ?? "null" }}
+					</span>
+				</div>
+			</section>
+
+			<section class="state-panel__section">
+				<h3>Context (reactive)</h3>
+				<pre class="state-panel__dump">{{ contextSummary }}</pre>
+			</section>
+
+			<section class="state-panel__section">
+				<h3>Controls</h3>
+				<div class="state-panel__controls">
+					<button
+						class="ctrl"
+						@click="flow.back()"
+						:disabled="flow.isFirst.value"
+					>
+						← Back
+					</button>
+					<button class="ctrl" @click="flow.reset()">↺ Reset</button>
+					<button class="ctrl" @click="forceError">Force error</button>
+				</div>
+				<div class="state-panel__controls">
+					<button
+						v-for="p in flow.pages.value"
+						:key="p.name"
+						class="ctrl ctrl--sm"
+						:class="{ 'ctrl--active': flow.pageName.value === p.name }"
+						@click="safeGoTo(p.name)"
+						:title="`Jump to '${p.name}'`"
+					>
+						{{ p.name }}
+					</button>
+				</div>
+			</section>
+
+			<section class="state-panel__section">
+				<h3>Tips</h3>
+				<ul class="state-panel__tips">
+					<li>
+						Branching is via <code>when: (ctx) =&gt; …</code> on each page def.
+					</li>
+					<li>
+						Actions can be a string (named op), an inline function, or
+						<code>false</code> to disable.
+					</li>
+					<li>
+						The QR + final page show how to read back from
+						<code>flow.context</code>.
+					</li>
+				</ul>
+			</section>
+		</aside>
+
+		<!-- The renderer. Slots forward through to the current page's slots. -->
+		<main class="flow-area">
+			<ExperienceFlow :flow="flow">
+				<!--
+          Custom loading + error UI — replaces the default overlays.
+          These slots receive scoped props: `loading` gets nothing, `error`
+          gets `{ error, retry }`.
+        -->
+				<template #loading>
+					<div class="custom-loading">
+						<div class="custom-loading__spinner" />
+						<p>Talking to the platform…</p>
+					</div>
+				</template>
+
+				<template #error="{ error, retry }">
+					<div class="custom-error">
+						<h3>Something went wrong</h3>
+						<p>{{ error.message }}</p>
+						<button class="custom-error__btn" @click="retry">Dismiss</button>
+					</div>
+				</template>
+			</ExperienceFlow>
+		</main>
+	</div>
+</template>
+
+<script setup>
+import { computed, reactive } from "vue"
+import {
+	useExperience,
+	useExperienceApi,
+	withExperienceDefaults,
+	ExperienceFlow,
+	WelcomePage,
+	TermsPage,
+	OptionsPage,
+	CameraPage,
+	CameraReviewPage,
+	DrawingPage,
+	NotepadPage,
+	LoadingPage,
+	FinalPage,
+} from "@gxp-dev/uikit"
+// The uikit ships Tailwind utilities + theme tokens used by every page below.
+// Imported here so the styles only load when the experience demo opens.
+import "@gxp-dev/uikit/styles"
+import { useGxpStore } from "@/stores/gxpPortalConfigStore"
+
+defineEmits(["navigate"])
+
+const gxpStore = useGxpStore()
+
+/* ─── Step 1: bridge gxpStore.callApi to the uikit's callApi shape ──────────
+ *
+ * uikit expects:    (endpoint, payload) => Promise<T>
+ * gxpStore offers:  (operationId, permissionIdentifier, data) => Promise<T>
+ *
+ * For the demo we mock the network so it works offline. In production replace
+ * the mock with the real `gxpStore.callApi(endpoint, '', payload)` line below.
+ */
+const MOCK_LATENCY_MS = 800
+
+async function mockCallApi(endpoint, payload) {
+	console.log("[demo] callApi", endpoint, payload)
+	await new Promise((r) => setTimeout(r, MOCK_LATENCY_MS))
+
+	// Simulate the {data: …} envelope the real platform returns.
+	if (endpoint === "social_stream.createPost") {
+		return {
+			data: {
+				id: Math.floor(Math.random() * 10_000),
+				file_url:
+					payload instanceof FormData
+						? URL.createObjectURL(payload.get("blob"))
+						: "https://placehold.co/600x400?text=Demo+Post",
+				caption: payload?.caption ?? null,
+			},
+		}
+	}
+	return { data: { ok: true } }
+}
+
+// Real wiring would look like this:
+//   const callApi = (endpoint, payload) => gxpStore.callApi(endpoint, "", payload)
+const callApi = mockCallApi
+
+/* ─── Step 2: build the API adapter ────────────────────────────────────────
+ *
+ * useExperienceApi turns `callApi` into typed named operations:
+ *   api.publishPost(data)  → callApi('social_stream.createPost', data)
+ *   api.createPrintJob({…})
+ *   api.processImage({blob, prompt})
+ *   etc.
+ *
+ * You can override specific operations or remap endpoints — useful when your
+ * backend uses different operationIds than the defaults.
+ */
+const api = useExperienceApi({
+	callApi,
+
+	// Per-op override example: replace the whole publishPost impl.
+	// overrides: {
+	//   publishPost: async (data) => ({ id: 1, file_url: '...' }),
+	// },
+
+	// Endpoint remap example: keep default behavior but call a different op.
+	// endpoints: {
+	//   publishPost: 'legacy.posts.create',
+	// },
+})
+
+/* ─── Step 3: custom-tag a page with defaults ───────────────────────────────
+ *
+ * `withExperienceDefaults` attaches a default `action` + `resultKey` to a page
+ * component, so the flow knows what to do when that page emits `next(data)`.
+ *
+ * Built-in pages already declare their defaults. For your own pages, wrap them.
+ */
+const TaggedNotepad = withExperienceDefaults(NotepadPage, {
+	action: async (payload) => {
+		// Inline function action — perfect for one-off work or composing API calls.
+		console.log("[demo] note submitted:", payload.caption)
+		return { savedAt: Date.now(), caption: payload.caption }
+	},
+	resultKey: "note",
+})
+
+/* ─── Step 4: define the flow ──────────────────────────────────────────────
+ *
+ * `pages` is an ordered array. Each entry has:
+ *   - name:       string key (used by goTo and as default resultKey)
+ *   - component:  any Vue component (built-in or your own)
+ *   - props:      passed straight through to the page
+ *   - when:       (ctx) => boolean — skip the page when this returns false
+ *   - action:     'publishPost' | (data, ctx, api) => Promise<T> | false
+ *   - resultKey:  where to stash the action's return value in `flow.context`
+ *
+ * Three action shapes are demonstrated below.
+ */
+const flow = useExperience({
+	api,
+
+	// Seed values on the context so pages can read from them.
+	initialContext: {
+		brand: "Acme",
+		attendeeName: gxpStore.getSetting("company_name") || "Friend",
+	},
+
+	pages: [
+		// ── Intro ────────────────────────────────────────────────────────────
+		{
+			name: "welcome",
+			component: WelcomePage,
+			props: {
+				title: "Welcome to the Demo Kiosk",
+				subtitle: "A guided tour of the experience-flow system",
+				ctaText: "Let's begin →",
+			},
+		},
+
+		{
+			name: "terms",
+			component: TermsPage,
+			// Skip terms entirely if the user already accepted them in a prior run.
+			when: (ctx) => !ctx.termsAccepted,
+			props: {
+				title: "Quick consent",
+				html: `
+          <p>By tapping <strong>Accept</strong> you agree this is a demo and
+          no real data leaves your browser.</p>
+          <p>Hit <em>Reset</em> in the side panel to start over at any time.</p>
+        `,
+				checkboxLabel: "I'm in",
+			},
+			// No action — TermsPage emits { accepted: true } and the flow stashes
+			// it under resultKey 'termsAccepted' (its built-in default).
+		},
+
+		// ── Path picker (branching) ──────────────────────────────────────────
+		{
+			name: "pick",
+			component: OptionsPage,
+			props: {
+				title: "Pick how you'd like to participate",
+				subtitle: "We'll show a different flow for each",
+				options: [
+					{ key: "photo", label: "📷 Take a photo" },
+					{ key: "drawing", label: "🎨 Draw something" },
+					{ key: "note", label: "✍️ Leave a note" },
+				],
+				emitKeyOnly: true, // stash just the key string in ctx.choice
+			},
+		},
+
+		// ── Photo branch ─────────────────────────────────────────────────────
+		{
+			name: "capture",
+			component: CameraPage,
+			when: (ctx) => ctx.choice === "photo",
+			props: {
+				countdown: 3,
+				mirrored: true,
+			},
+			// CameraPage emits next(blob: Blob) → ctx.photoBlob (its default resultKey)
+		},
+		{
+			name: "review",
+			component: CameraReviewPage,
+			when: (ctx) => ctx.choice === "photo",
+			props: { allowCaption: true },
+			// ⚡ This page's built-in default action is 'publishPost' — i.e. it
+			// looks up api.publishPost and calls it with the emitted payload. The
+			// result is stashed in ctx.post. No wiring needed here.
+		},
+
+		// ── Drawing branch ───────────────────────────────────────────────────
+		{
+			name: "draw",
+			component: DrawingPage,
+			when: (ctx) => ctx.choice === "drawing",
+			props: {
+				penColors: ["#000000", "#dc2626", "#2563eb", "#16a34a", "#facc15"],
+				backgroundColors: ["#ffffff", "#fef3c7", "#dbeafe"],
+				submitLabel: "Submit drawing",
+			},
+			// Inline function action that uploads the rendered blob.
+			action: async (blob, _ctx, apiArg) => {
+				return await apiArg.publishPost({ blob, caption: "From the easel" })
+			},
+			resultKey: "post",
+		},
+
+		// ── Note branch (uses our pre-tagged version) ────────────────────────
+		{
+			name: "note",
+			component: TaggedNotepad,
+			when: (ctx) => ctx.choice === "note",
+			props: { title: "Write your message", maxCharacters: 140 },
+		},
+
+		// ── Async wait (only for paths that produced media) ──────────────────
+		{
+			name: "saving",
+			component: LoadingPage,
+			// Only show this for paths where we produced a post; the 'note' path
+			// already finished its custom action.
+			when: (ctx) => Boolean(ctx.post),
+			props: {
+				messages: [
+					"Hanging your masterpiece in the gallery…",
+					"Almost there…",
+					"Polishing the frame…",
+				],
+				messageInterval: 1.4,
+				// The LoadingPage's `task` runs as soon as the page mounts. Resolves
+				// → next(result); rejects → flow.error. Great for polling.
+				task: async (ctx) => {
+					await new Promise((r) => setTimeout(r, 1800))
+					return { hangedAt: Date.now(), postId: ctx.post?.id }
+				},
+			},
+		},
+
+		// ── Outcome ─────────────────────────────────────────────────────────
+		{
+			name: "final",
+			component: FinalPage,
+			props: {
+				title: "✨ All done!",
+				qrCaption: "Scan to take it home",
+				qrUrl: "https://placehold.co/200x200/000/fff?text=QR",
+				actions: [
+					{ key: "email", label: "Email me", variant: "primary" },
+					{ key: "download", label: "Download", variant: "secondary" },
+				],
+				showRestart: true,
+			},
+			// FinalPage emits `next` (restart) and `action(key)`. The flow's
+			// `onComplete` (below) fires when we step past the last visible page.
+		},
+	],
+
+	// Fires when next() is called on the last visible page. Great place to
+	// analytics-log or kick off a post-flow handoff.
+	onComplete: (ctx) => {
+		console.log("[demo] flow complete; final context:", { ...ctx })
+		// Restart from the top so the kiosk is ready for the next user.
+		flow.reset()
+	},
+
+	// Optional global error trap. Return `true` to swallow so the flow stays
+	// on the current page (otherwise the error appears in the error overlay).
+	onError: (err, ctx) => {
+		console.warn("[demo] action threw:", err, { ctx: { ...ctx } })
+		// Return nothing → show the error overlay.
+	},
+})
+
+/* ─── Side-panel helpers ───────────────────────────────────────────────── */
+
+const reactiveCtx = reactive(flow.context)
+
+const contextSummary = computed(() => {
+	const snapshot = {}
+	for (const [k, v] of Object.entries(reactiveCtx)) {
+		if (v instanceof Blob) {
+			snapshot[k] = `Blob<${v.type || "binary"}, ${v.size}B>`
+		} else if (v && typeof v === "object") {
+			snapshot[k] = v
+		} else {
+			snapshot[k] = v
+		}
+	}
+	return JSON.stringify(snapshot, null, 2)
+})
+
+async function safeGoTo(name) {
+	try {
+		await flow.goTo(name)
+	} catch (err) {
+		// goTo throws if the target's `when` predicate is currently false.
+		console.warn(err.message)
+	}
+}
+
+function forceError() {
+	// Tap into the same surface a thrown action would. Useful for previewing
+	// the custom #error slot.
+	flow.error.value = new Error("Demo error — dismiss to continue")
+}
+</script>
+
+<style scoped>
+.demo-experience-page {
+	display: grid;
+	grid-template-columns: 320px 1fr;
+	height: 100vh;
+	min-height: 600px;
+	background: #0f172a;
+	color: #e2e8f0;
+	font-family:
+		-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+}
+
+/* ─── State panel ─────────────────────────────────────────────────────── */
+.state-panel {
+	background: #111827;
+	border-right: 1px solid #1f2937;
+	padding: 20px;
+	overflow-y: auto;
+}
+
+.state-panel__header {
+	margin-bottom: 20px;
+}
+
+.back-link {
+	background: none;
+	border: 0;
+	color: #93c5fd;
+	font-size: 13px;
+	cursor: pointer;
+	padding: 0;
+	margin-bottom: 12px;
+}
+.back-link:hover {
+	color: #bfdbfe;
+}
+
+.state-panel h2 {
+	margin: 0;
+	font-size: 16px;
+	color: #f1f5f9;
+}
+
+.state-panel__section {
+	margin-top: 20px;
+	padding-top: 16px;
+	border-top: 1px solid #1f2937;
+}
+.state-panel__section h3 {
+	margin: 0 0 8px 0;
+	font-size: 11px;
+	font-weight: 600;
+	text-transform: uppercase;
+	letter-spacing: 0.06em;
+	color: #94a3b8;
+}
+
+.state-panel__value {
+	font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+	font-size: 14px;
+	color: #fbbf24;
+}
+
+.state-panel__meta {
+	margin-top: 6px;
+	font-size: 11px;
+	color: #64748b;
+	line-height: 1.6;
+}
+
+.pill {
+	display: inline-block;
+	padding: 1px 6px;
+	border-radius: 4px;
+	background: #1e293b;
+	color: #cbd5e1;
+	font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+}
+.pill--on {
+	background: #1e3a8a;
+	color: #bfdbfe;
+}
+.pill--err {
+	background: #7f1d1d;
+	color: #fecaca;
+}
+
+.state-panel__dump {
+	font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+	font-size: 11px;
+	line-height: 1.5;
+	color: #cbd5e1;
+	background: #0b1220;
+	padding: 10px;
+	border-radius: 6px;
+	border: 1px solid #1f2937;
+	max-height: 220px;
+	overflow: auto;
+	white-space: pre-wrap;
+	margin: 0;
+}
+
+.state-panel__controls {
+	display: flex;
+	flex-wrap: wrap;
+	gap: 6px;
+	margin-top: 8px;
+}
+.ctrl {
+	font-size: 12px;
+	background: #1f2937;
+	color: #e2e8f0;
+	border: 1px solid #334155;
+	border-radius: 5px;
+	padding: 5px 9px;
+	cursor: pointer;
+}
+.ctrl:hover {
+	background: #374151;
+}
+.ctrl:disabled {
+	opacity: 0.4;
+	cursor: not-allowed;
+}
+.ctrl--sm {
+	font-size: 11px;
+	padding: 3px 7px;
+}
+.ctrl--active {
+	background: #1e40af;
+	border-color: #3b82f6;
+	color: #dbeafe;
+}
+
+.state-panel__tips {
+	font-size: 12px;
+	color: #94a3b8;
+	padding-left: 18px;
+	margin: 0;
+	line-height: 1.6;
+}
+.state-panel__tips code {
+	background: #0b1220;
+	padding: 1px 5px;
+	border-radius: 3px;
+	font-size: 11px;
+	color: #fbbf24;
+}
+
+/* ─── Flow area ──────────────────────────────────────────────────────── */
+.flow-area {
+	background: var(--background, #f8fafc);
+	color: var(--foreground, #0f172a);
+	position: relative;
+	overflow: hidden;
+}
+
+/* ─── Custom loading / error overrides ───────────────────────────────── */
+.custom-loading {
+	display: flex;
+	flex-direction: column;
+	align-items: center;
+	gap: 14px;
+	color: #1e40af;
+	font-weight: 500;
+}
+.custom-loading__spinner {
+	width: 48px;
+	height: 48px;
+	border: 4px solid #93c5fd;
+	border-right-color: transparent;
+	border-radius: 50%;
+	animation: demo-spin 0.9s linear infinite;
+}
+@keyframes demo-spin {
+	to {
+		transform: rotate(360deg);
+	}
+}
+
+.custom-error {
+	max-width: 420px;
+	padding: 24px;
+	background: white;
+	border: 2px solid #dc2626;
+	border-radius: 10px;
+	text-align: center;
+}
+.custom-error h3 {
+	margin: 0 0 8px 0;
+	color: #b91c1c;
+}
+.custom-error p {
+	margin: 0 0 14px 0;
+	color: #374151;
+}
+.custom-error__btn {
+	background: #dc2626;
+	color: white;
+	border: 0;
+	padding: 8px 18px;
+	border-radius: 6px;
+	cursor: pointer;
+	font-weight: 500;
+}
+
+/* Stack on narrow screens (mobile preview in dev) */
+@media (max-width: 720px) {
+	.demo-experience-page {
+		grid-template-columns: 1fr;
+		grid-template-rows: auto 1fr;
+	}
+	.state-panel {
+		border-right: 0;
+		border-bottom: 1px solid #1f2937;
+		max-height: 240px;
+	}
+}
+</style>

package/template/src/DemoPage.vue

@@ -22,6 +22,19 @@
 				</p>
 			</header>
 
+			<!-- Cross-page demo: navigate to the experience-flow demo -->
+			<section class="panel demo-link-panel">
+				<h2>Experience Flow Demo <span class="tag">@gxp-dev/uikit</span></h2>
+				<p class="hint">
+					A full state-machine-driven kiosk flow showing how to use
+					<code>useExperience</code>, the page library, async actions, branching
+					paths, and slot customization — all in one annotated file.
+				</p>
+				<button class="btn primary" @click="$emit('navigate', 'experience')">
+					Open Experience Demo →
+				</button>
+			</section>
+
 			<!-- gxp-settings + gxp-string: read from manifest.settings instead of strings -->
 			<section class="panel">
 				<h2>Settings <span class="tag">gxp-settings</span></h2>
@@ -154,6 +167,8 @@
 
 .hero h1 {
 	margin: 0 0 8px 0;
+	font-size: 28px;
+	font-weight: 700;
 	color: v-bind('gxpStore.getSetting("primary_color")');
 }
 
@@ -345,6 +360,8 @@ defineOptions({
 	inheritAttrs: false,
 })
 
+defineEmits(["navigate"])
+
 import { ref, onMounted, onUnmounted } from "vue"
 import { useGxpStore } from "@/stores/gxpPortalConfigStore"
 

package/template/src/Plugin.vue

@@ -1,11 +1,17 @@
 <template>
 	<!-- Your Custom Plugin Content -->
-	<DemoPage :router="mockRouter" />
+	<DemoPage v-if="route === 'home'" :router="mockRouter" @navigate="navigate" />
+	<DemoExperience v-else-if="route === 'experience'" @navigate="navigate" />
 </template>
 
 <script setup>
 import { ref, shallowRef } from "vue"
 import DemoPage from "@/DemoPage.vue"
+import DemoExperience from "@/DemoExperience.vue"
+
+// Note: @gxp-dev/uikit ships its own stylesheet (Tailwind + theme tokens). The
+// experience-flow demo imports it inside DemoExperience.vue so it only loads
+// when that page is opened.
 
 // Initialize the GxP store
 // This import is externalized to window.useGxpStore during build for platform compatibility
@@ -15,6 +21,13 @@ const gxpStore = useGxpStore()
 gxpStore.sockets?.primary.listenForStateChange((event) => {
 	console.log("🔗 GXP Store: State change event received", event)
 })
+
+// Lightweight in-app routing between the two demo pages. Swap for vue-router
+// in a real plugin if you need URL-aware nav.
+const route = ref("home")
+const navigate = (next) => {
+	route.value = next
+}
 </script>
 
 <style>

package/mcp/lib/uikit-tools.js

@@ -1,181 +0,0 @@
-/**
- * MCP tools for @gxp-dev/uikit introspection.
- *
- *   - list_uikit_components : enumerate components exported by the version
- *     of @gxp-dev/uikit installed in the *plugin project's* node_modules
- *     (not the toolkit's). Resolves the package relative to process.cwd(),
- *     parses named exports out of dist/index.d.ts, and returns sorted
- *     PascalCase names plus the package version.
- *
- * We parse the .d.ts with a regex pair (no TS AST) because the file is the
- * built output and is shaped by the package's own build, not by us. Edge
- * cases that the regex misses (e.g. nested namespace exports) are
- * acceptable: the agent gets a strong starting set and can fall back to
- * docs_search for anything unusual.
- */
-
-const fs = require("fs")
-const path = require("path")
-
-function contentResult(obj) {
-	return {
-		content: [{ type: "text", text: JSON.stringify(obj, null, 2) }],
-	}
-}
-
-/**
- * Resolve @gxp-dev/uikit from the given cwd. Returns { root, pkg } where
- * root is the absolute path to the uikit package directory and pkg is the
- * parsed package.json, or null if uikit is not installed at any level.
- *
- * We mimic Node's node_modules walk-up rather than calling
- * require.resolve("@gxp-dev/uikit/...") because the uikit's package.json
- * declares a strict `exports` field with only `import` and `types`
- * conditions. From a CJS context, require.resolve fails against that
- * exports map even though the directory exists on disk. Walking the
- * filesystem directly sidesteps it and works under npm, pnpm (where
- * @gxp-dev/uikit is a symlink into .pnpm), and yarn workspaces.
- */
-function resolveUikit(cwd = process.cwd()) {
-	let dir = path.resolve(cwd)
-	while (dir) {
-		const candidate = path.join(dir, "node_modules", "@gxp-dev", "uikit")
-		const pkgPath = path.join(candidate, "package.json")
-		if (fs.existsSync(pkgPath)) {
-			try {
-				const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"))
-				if (pkg && pkg.name === "@gxp-dev/uikit") {
-					return { root: candidate, pkg }
-				}
-			} catch {
-				// malformed package.json — keep walking
-			}
-		}
-		const parent = path.dirname(dir)
-		if (parent === dir) break
-		dir = parent
-	}
-	return null
-}
-
-/**
- * Pull named exports out of a .d.ts source string. Picks up:
- *   - export declare const/let/var Foo
- *   - export declare function Foo
- *   - export declare class Foo
- *   - export declare interface Foo
- *   - export declare type Foo
- *   - export declare enum Foo
- *   - export { Foo, Bar as Baz }
- */
-function parseNamedExports(source) {
-	const names = new Set()
-
-	const declRe =
-		/export\s+(?:declare\s+)?(?:const|let|var|function|class|interface|type|enum)\s+([A-Za-z_$][A-Za-z0-9_$]*)/g
-	let m
-	while ((m = declRe.exec(source)) !== null) {
-		names.add(m[1])
-	}
-
-	const braceRe = /export\s*\{([^}]+)\}/g
-	while ((m = braceRe.exec(source)) !== null) {
-		const inner = m[1]
-		for (const rawPart of inner.split(",")) {
-			const part = rawPart.trim()
-			if (!part) continue
-			const aliasMatch = part.match(
-				/^[A-Za-z_$][A-Za-z0-9_$]*\s+as\s+([A-Za-z_$][A-Za-z0-9_$]*)/,
-			)
-			if (aliasMatch) {
-				names.add(aliasMatch[1])
-				continue
-			}
-			const nameMatch = part.match(/^([A-Za-z_$][A-Za-z0-9_$]*)/)
-			if (nameMatch) names.add(nameMatch[1])
-		}
-	}
-
-	return Array.from(names)
-}
-
-function listUikitComponents({ filter, cwd } = {}) {
-	const resolved = resolveUikit(cwd || process.cwd())
-	if (!resolved) {
-		return {
-			ok: false,
-			error:
-				"Could not resolve @gxp-dev/uikit from the current project. Install it with `npm install @gxp-dev/uikit` and re-run mcp-serve from the plugin project root.",
-		}
-	}
-	const { root, pkg } = resolved
-	const dtsPath = path.join(root, "dist", "index.d.ts")
-	if (!fs.existsSync(dtsPath)) {
-		return {
-			ok: false,
-			error: `@gxp-dev/uikit is installed at ${root} but dist/index.d.ts is missing. The package may not have been built.`,
-			resolved: root,
-		}
-	}
-
-	const src = fs.readFileSync(dtsPath, "utf-8")
-	const all = parseNamedExports(src)
-	const pascal = all.filter((n) => /^[A-Z]/.test(n)).sort()
-
-	let filtered = pascal
-	if (filter) {
-		const f = String(filter).toLowerCase()
-		filtered = pascal.filter((n) => n.toLowerCase().includes(f))
-	}
-
-	return {
-		ok: true,
-		package: {
-			name: pkg.name,
-			version: pkg.version || null,
-			root,
-		},
-		count: filtered.length,
-		components: filtered,
-	}
-}
-
-const UIKIT_TOOLS = [
-	{
-		name: "list_uikit_components",
-		description:
-			"Enumerate components exported by the @gxp-dev/uikit package installed in the current plugin project. Reads named exports from the built dist/index.d.ts and returns the PascalCase names plus the package version. Resolves uikit relative to the project (process.cwd()), not the toolkit, so the agent sees exactly what the project can import. Pass `filter` for a case-insensitive substring match.",
-		inputSchema: {
-			type: "object",
-			properties: {
-				filter: {
-					type: "string",
-					description:
-						"Case-insensitive substring filter applied to component names.",
-				},
-			},
-		},
-	},
-]
-
-async function handleUikitToolCall(name, args = {}) {
-	switch (name) {
-		case "list_uikit_components":
-			return contentResult(listUikitComponents(args))
-		default:
-			throw new Error(`Unknown uikit tool: ${name}`)
-	}
-}
-
-function isUikitTool(name) {
-	return UIKIT_TOOLS.some((t) => t.name === name)
-}
-
-module.exports = {
-	UIKIT_TOOLS,
-	handleUikitToolCall,
-	isUikitTool,
-	listUikitComponents,
-	parseNamedExports,
-	resolveUikit,
-}