mikser-io 7.12.0 → 8.0.0

package/README.md

@@ -10,7 +10,7 @@
 
 Built for Node.js around a strict lifecycle and a composable plugin system. Every document, asset, and template flows through the same pipeline; plugins hook in at any phase. The same engine runs a single markdown blog and a multi-language publishing platform with PDF / email / AI-augmented asset pipelines — same lifecycle, more plugins.
 
-It's MIT-licensed, runs on Node 18+, has zero hosted dependencies, and the entire content tree it manages is a folder of `.md` and `.yml` files you can copy, diff, and version-control. **The portability promise is the architecture, not a feature.**
+It's MIT-licensed, runs on Node, has zero hosted dependencies, and the entire content tree it manages is a folder of `.md` and `.yml` files you can copy, diff, and version-control. **The portability promise is the architecture, not a feature.**
 
 > **New to mikser?** Read the [Architecture Overview](./documentation/overview.md) — one document, end-to-end walkthrough of how a file becomes a deployed page across all twenty lifecycle phases. It's the doc most projects need first.
 
@@ -84,7 +84,7 @@ Add `--mcp` to your mikser command and any MCP-speaking client — Claude Deskto
 - read every entity in the catalog
 - write new content files (markdown, layouts, configuration) — writes land on disk and the next cycle picks them up
 - render any layout for preview without touching the output folder
-- **surface rendered UI inline in the conversation** — `mikser_preview_ui` runs an entity through a layout that declares `mcpUi` frontmatter and returns the HTML as a UI block the host can show; an approve/reject button on that block sends the result straight back to the agent
+- **surface interactive UI inline in the conversation** — you author the UI as a normal mikser layout with YAML frontmatter (`mcpUi: { mode, actions }`). The agent reads `mikser://mcp-ui/modes` to discover what UIs your project supports, calls `mikser_preview_ui` to render one against an entity, and the host displays the result as a sandboxed iframe in the chat. Buttons in the UI deliver their click back as a separate MCP tool turn — the iframe sends a JSON-RPC `tools/call` to the host over `postMessage` per the [MCP Apps spec](https://github.com/modelcontextprotocol/ext-apps), which the host bridges into a real `mikser_ui_action` invocation. The agent sees a structured `{action, entityId, payload}` result; if you declared `mcpUi.handler.url`, mikser forwards the action to your webhook first and uses its response. No separate UI framework, no glue code; layouts are still just layouts
 - watch every build log as it streams past
 - introspect engine state — current lifecycle phase, effective config, recent log buffer
 
@@ -103,7 +103,7 @@ When an AI agent edits ten files, the next question is: *did it do what I asked?
 - **"Did I update every article that needed it?"** — semantic search finds anything that still matches the old tone or phrasing the agent was supposed to change.
 - **"What else mentions this person, product, or topic?"** — mikser knows how content references content. "Show me every page that mentions Dick" returns the list instantly, no full-tree scan.
 - **"Did anything break?"** — if a reference points at something that no longer exists, mikser surfaces it as a warning. The build either completes cleanly or doesn't.
-- **"Can I see what this looks like before publishing?"** — render any single page or section on demand, no full rebuild, no staging deploy.
+- **"Can I see what this looks like before publishing?"** — render any single page or section on demand, no full rebuild, no staging deploy. With an `mcpUi` layout, the agent surfaces the rendered preview *inside the chat* with approve/reject controls; one click sends the result back as the tool response.
 - **"What changed since I last looked?"** — `git diff`. The catalog is plain files, so the audit trail is the same one your engineers already use for code.
 - **"Roll back this batch?"** — `git checkout`. Atomic. No database migration to undo, no version-history-feature to learn.
 
@@ -153,7 +153,7 @@ The engine is what stays stable — the lifecycle, the catalog, the file-based c
 
 ## Client SDKs
 
-The `api`, `vector`, and `schemas` plugins are paired with client-side SDKs so a frontend (or another Node app) can talk to a running mikser server without rolling its own `fetch` glue or type contracts. Zero dependencies, runs in browsers / Node 18+ / Deno / Bun / Workers.
+The `api`, `vector`, and `schemas` plugins are paired with client-side SDKs so a frontend (or another Node app) can talk to a running mikser server without rolling its own `fetch` glue or type contracts. Zero dependencies, runs in browsers / Node / Deno / Bun / Workers.
 
 **Transport-level:**
 
@@ -190,7 +190,7 @@ For a working starter — config with a real plugin set, sample `documents/`, ex
 
 - **Lifecycle** — Processing runs through fixed phases: initialize → load → import → process → persist → render → finalize. Plugins hook into any phase.
 - **Entities** — Everything is an entity (document, file, layout, asset). Entities flow through the journal and are tracked in the catalog.
-- **References between entities** — Front-matter keys starting with `$` (e.g. `$author: /authors/dick`) are references. The engine projects them to plain keys (`meta.author`) for templates and SDK consumers; the schemas plugin auto-validates them; the api can `expand` them inline for one-trip graph fetches. The engine also maintains an inverse-reference index at `runtime.refs.*` (graph queries, rename cascade, live-expand subscriptions, MCP tools `mikser_refs_inbound` / `_outbound` / `_broken` / `_rename`). See [ADR-0007](./documentation/decisions/0007-references-declaration-and-expansion.md).
+- **References between entities** — A front-matter key starting with `$` (e.g. `$author: /authors/dick`) points at another entity. The engine knows the whole graph: templates can follow the links, the schemas plugin checks they resolve, and a single query can pull referenced entities along inline instead of one round trip per link. See [ADR-0007](./documentation/decisions/0007-references-declaration-and-expansion.md).
 - **Plugins** — Functionality is delivered via plugins. Built-in plugins handle common sources (documents, files, layouts, assets). Custom plugins can be added to any project.
 - **Runtime Singleton** — A plain module-level object holds all global state and coordinates the lifecycle. The ES module cache guarantees every importer gets the same instance.
 - **Watch Mode** — In watch mode, file changes trigger incremental re-processing without restarting.
@@ -221,7 +221,7 @@ What you get from how this project is built:
 
 The earliest version of mikser was inspired by [DocPad](https://github.com/docpad/docpad) (Benjamin Lupton, with Michael Duane Mooring and Rob Loach). DocPad's "freeway, not a box" philosophy — files on disk, any pre-processor or template engine, plugin-by-convention extension — shaped how mikser started.
 
-Mikser itself has a previous chapter: the [legacy 7.x line](https://github.com/almero-digital-marketing/mikser) (last release 2022) introduced the real-time SSG model the current engine still carries forward. The redesign dropped MongoDB (the catalog lives in-process now, not in a database), modernized to Node 18+ ESM with a structured 20-phase lifecycle, added the live SSE channel that powers the framework SDKs, and replaced cluster-based rendering with an async worker pool. Same intent — content as files, real-time previews, multi-format output at scale — clearer foundations.
+Mikser itself has a previous chapter: the [legacy 7.x line](https://github.com/almero-digital-marketing/mikser) (last release 2022) introduced the real-time SSG model the current engine still carries forward. The redesign dropped MongoDB (the catalog lives in-process now, not in a database), modernized to Node ESM with a structured 20-phase lifecycle, added the live SSE channel that powers the framework SDKs, and replaced cluster-based rendering with an async worker pool. Same intent — content as files, real-time previews, multi-format output at scale — clearer foundations.
 
 ## Documentation Index
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "mikser-io",
-	"version": "7.12.0",
+	"version": "8.0.0",
 	"description": "<p align=\"center\">   <img src=\"mikser-lockup-stacked.svg\" alt=\"mikser\" width=\"198\" /> </p>",
 	"main": "index.js",
 	"scripts": {

package/src/mcp.js

@@ -75,9 +75,11 @@ export function createMcpSubstrate() {
 
     function bind(server, filters = {}) {
         const { allowedTools, allowedResources, allowedPrompts } = filters
+        const bound = { tools: 0, resources: 0, prompts: 0 }
         for (const args of registrations.tools) {
             if (!matchesAny(args[0], allowedTools)) continue
             server.registerTool(...args)
+            bound.tools++
         }
         for (const args of registrations.resources) {
             // Resource registrations are (name, uri, config, handler).
@@ -87,11 +89,14 @@ export function createMcpSubstrate() {
             const uri = typeof args[1] === 'string' ? args[1] : args[0]
             if (!matchesAny(uri, allowedResources)) continue
             server.registerResource(...args)
+            bound.resources++
         }
         for (const args of registrations.prompts) {
             if (!matchesAny(args[0], allowedPrompts)) continue
             server.registerPrompt(...args)
+            bound.prompts++
         }
+        return bound
     }
 
     const substrate = {
@@ -101,22 +106,58 @@ export function createMcpSubstrate() {
         // shape, it just records and replays.
         registerTool(...args) {
             registrations.tools.push(args)
+            const name = args[0]
+            let replayed = 0
+            const replayErrors = []
             for (const s of activeServers) {
-                try { s.registerTool(...args) } catch { /* dup, etc. */ }
+                try { s.registerTool(...args); replayed++ }
+                catch (err) { replayErrors.push(err.message) }
+            }
+            const log = runtime.engine?.logger
+            if (log) {
+                log.debug('MCP substrate: registered tool %s (total=%d, live-replayed=%d/%d)',
+                    name, registrations.tools.length, replayed, activeServers.size)
+                for (const msg of replayErrors) {
+                    log.debug('MCP substrate: live-replay of tool %s failed on a session server: %s', name, msg)
+                }
             }
             return substrate
         },
         registerResource(...args) {
             registrations.resources.push(args)
+            const uri = typeof args[1] === 'string' ? args[1] : args[0]
+            let replayed = 0
+            const replayErrors = []
             for (const s of activeServers) {
-                try { s.registerResource(...args) } catch { /* dup */ }
+                try { s.registerResource(...args); replayed++ }
+                catch (err) { replayErrors.push(err.message) }
+            }
+            const log = runtime.engine?.logger
+            if (log) {
+                log.debug('MCP substrate: registered resource %s (total=%d, live-replayed=%d/%d)',
+                    uri, registrations.resources.length, replayed, activeServers.size)
+                for (const msg of replayErrors) {
+                    log.debug('MCP substrate: live-replay of resource %s failed on a session server: %s', uri, msg)
+                }
             }
             return substrate
         },
         registerPrompt(...args) {
             registrations.prompts.push(args)
+            const name = args[0]
+            let replayed = 0
+            const replayErrors = []
             for (const s of activeServers) {
-                try { s.registerPrompt(...args) } catch { /* dup */ }
+                try { s.registerPrompt(...args); replayed++ }
+                catch (err) { replayErrors.push(err.message) }
+            }
+            const log = runtime.engine?.logger
+            if (log) {
+                log.debug('MCP substrate: registered prompt %s (total=%d, live-replayed=%d/%d)',
+                    name, registrations.prompts.length, replayed, activeServers.size)
+                for (const msg of replayErrors) {
+                    log.debug('MCP substrate: live-replay of prompt %s failed on a session server: %s', name, msg)
+                }
             }
             return substrate
         },
@@ -136,17 +177,31 @@ export function createMcpSubstrate() {
         //   allowedResources: ['mikser://lifecycle', 'mikser://logs/*']
         // Omit a filter (or pass '*') to allow everything in that
         // category — that's the backward-compat default.
-        _createServer({ allowedTools, allowedResources, allowedPrompts } = {}) {
+        createServer({ allowedTools, allowedResources, allowedPrompts } = {}) {
             const server = new McpServer(
                 { name: 'mikser-io', version: packageInfo.version },
                 { capabilities: { tools: {}, resources: {}, logging: {} } },
             )
-            bind(server, { allowedTools, allowedResources, allowedPrompts })
+            const bound = bind(server, { allowedTools, allowedResources, allowedPrompts })
+            runtime.engine?.logger?.debug(
+                'MCP session server created (tools=%d/%d, resources=%d/%d, prompts=%d/%d)',
+                bound.tools, registrations.tools.length,
+                bound.resources, registrations.resources.length,
+                bound.prompts, registrations.prompts.length,
+            )
             return server
         },
-        _attach(server) { activeServers.add(server) },
-        _detach(server) { activeServers.delete(server) },
-        _activeServerCount() { return activeServers.size },
+        attach(server) {
+            activeServers.add(server)
+            runtime.engine?.logger?.debug(
+                'MCP session attached — active clients: %d', activeServers.size)
+        },
+        detach(server) {
+            activeServers.delete(server)
+            runtime.engine?.logger?.debug(
+                'MCP session detached — active clients: %d', activeServers.size)
+        },
+        activeServerCount() { return activeServers.size },
 
         // Send a logging-message notification to every connected
         // client. The SDK's per-session level filtering applies.
@@ -309,7 +364,7 @@ export function createMcpSubstrate() {
                     phase: runtime.phase ?? null,
                     workingFolder: runtime.options.workingFolder,
                     outputFolder: runtime.options.outputFolder,
-                    activeClients: substrate._activeServerCount(),
+                    activeClients: substrate.activeServerCount(),
                     server: serverInfo(),
                 }, null, 2),
             }],
@@ -373,6 +428,10 @@ export async function mountMcpOnExpress(app, substrate, defaultPath = '/mcp') {
     const endpoints = runtime.config.mcp?.endpoints
     const base = runtime.config.mcp?.base ?? defaultPath
 
+    runtime.engine?.logger?.debug(
+        'MCP mounting on Express (base=%s, endpoints=%d)',
+        base, endpoints ? Object.keys(endpoints).length : 1)
+
     if (endpoints && Object.keys(endpoints).length > 0) {
         for (const [name, ep] of Object.entries(endpoints)) {
             mountEndpoint(app, substrate, `${base}/${name}`, ep, name)
@@ -404,6 +463,8 @@ function mountEndpoint(app, substrate, path, ep, endpointName) {
         const presented = req.headers.authorization
         if (expectedAuth) {
             if (presented && presented !== expectedAuth) {
+                runtime.engine?.logger?.debug(
+                    'MCP auth denied at %s: invalid token (ip=%s)', path, req.ip)
                 res.status(401).json({
                     jsonrpc: '2.0',
                     error: { code: -32001, message: 'Invalid MCP token' },
@@ -416,6 +477,8 @@ function mountEndpoint(app, substrate, path, ep, endpointName) {
         }
         if (!presented || presented !== expectedAuth) {
             if (!ep.allowRemote && !isLoopback(req.ip)) {
+                runtime.engine?.logger?.debug(
+                    'MCP auth denied at %s: non-loopback without token (ip=%s)', path, req.ip)
                 res.status(403).json({
                     jsonrpc: '2.0',
                     error: {
@@ -436,7 +499,9 @@ function mountEndpoint(app, substrate, path, ep, endpointName) {
         }
 
         // New session — server filtered for this endpoint's surface.
-        const server = substrate._createServer({
+        runtime.engine?.logger?.debug(
+            'MCP new session at %s (ip=%s, method=%s)', path, req.ip, req.method)
+        const server = substrate.createServer({
             allowedTools:     ep.tools,
             allowedResources: ep.resources,
             allowedPrompts:   ep.prompts,
@@ -445,12 +510,12 @@ function mountEndpoint(app, substrate, path, ep, endpointName) {
             sessionIdGenerator: () => randomUUID(),
             onsessioninitialized: (id) => {
                 transports.set(id, transport)
-                substrate._attach(server)
+                substrate.attach(server)
             },
         })
         transport.onclose = () => {
             if (transport.sessionId) transports.delete(transport.sessionId)
-            substrate._detach(server)
+            substrate.detach(server)
         }
         await server.connect(transport)
         return transport.handleRequest(req, res, body)
@@ -519,6 +584,12 @@ export function wireLoggerToMcp(logger, substrate) {
             } catch { /* swallow — keep stdout pipeline working */ }
         }
     }
+    // No wire-up confirmation here — the wrapper has a load-bearing
+    // 1-broadcast-per-log-call invariant and a "skip missing methods"
+    // invariant. Operators still see the substrate's debug coverage
+    // (registrations, session lifecycle, auth deny) once the engine
+    // logger flows through. The "MCP mounted: …" info line at boot
+    // is the user-visible "ready" signal.
     return logger
 }
 
@@ -554,16 +625,3 @@ function format(template, args) {
 function pinoLevelNumber(name) {
     return { trace: 10, debug: 20, info: 30, warn: 40, error: 50, fatal: 60 }[name] ?? 30
 }
-
-// (whenMcpActive was removed in v7.4.0 — plugins now use the same
-// inline pattern as Express route registration: gate on the runtime
-// option inside whichever lifecycle hook makes sense.
-//
-//   onLoaded(async () => {
-//       if (runtime.options.mcp) {
-//           runtime.options.mcp.simpleTool(...)
-//       }
-//   })
-//
-// Reveals timing, matches the Express pattern, doesn't lock the
-// registration into onLoaded.)

package/src/plugins/layouts.js

@@ -403,7 +403,12 @@ export default ({
 
             if (data?.pages) {
                 if (!_.endsWith(entity.name, entity.format)) {
-                    for (let page = 0; page < data.pages - 1; page++) {
+                    // Loop bound is `< data.pages` (not `data.pages - 1`).
+                    // With 4 pages and the old bound, iteration only ran
+                    // page=0,1,2 and the 4th page was silently dropped —
+                    // the sitemap claimed "Page X of 4" but the destination
+                    // for page 4 was never produced.
+                    for (let page = 0; page < data.pages; page++) {
                         const pageEntity = _.cloneDeep(entity)
                         pageEntity.pages = data.pages
                         if (page) {

package/src/plugins/preview.js

@@ -24,11 +24,85 @@
 // wrapper over this surface.
 
 import path from 'node:path'
-import { randomUUID } from 'node:crypto'
+import { randomUUID, createHmac } from 'node:crypto'
 import { z } from 'zod'
 import { useRenderer } from '../api.js'
 import { mimeForEntity, matchEntity } from '../utils.js'
 
+// Forward an MCP-UI action to an external handler URL. Returns the
+// handler's JSON response, which becomes the tool result. Throws on
+// network error, non-2xx status, timeout, or invalid response shape —
+// callers fall back to pure-relay on throw.
+//
+// HMAC signing: when handler.secret is set, we sign the request body
+// with sha256(secret) and pass it in X-Mikser-Signature. Receivers
+// MUST verify before processing. When secret is unset, no signature
+// is sent (acceptable for dev; not recommended in production — see
+// ADR-0008).
+//
+// Extracted as a standalone function so it can be unit-tested with a
+// mock URL and so mikser_ui_action's main path stays readable.
+export async function forwardToHandler(handler, body) {
+    const { url, secret, timeout = 5000 } = handler
+    if (!url) throw new Error('forwardToHandler: handler.url is required')
+
+    const json = JSON.stringify({
+        ...body,
+        // Timestamp is set inside the forward, not by the caller, so
+        // a stale callback that came in via a slow network still has
+        // a fresh timestamp on the outgoing forward. Receivers that
+        // care can put their own.
+        timestamp: new Date().toISOString(),
+    })
+
+    const headers = {
+        'content-type':         'application/json',
+        'x-mikser-layout-id':   body.layoutId   ?? '',
+        'x-mikser-mode':        body.mode       ?? '',
+        'x-mikser-request-id':  randomUUID(),
+    }
+    if (secret) {
+        const sig = createHmac('sha256', secret).update(json).digest('hex')
+        headers['x-mikser-signature'] = `sha256=${sig}`
+    }
+
+    const ac = new AbortController()
+    const timer = setTimeout(() => ac.abort(), timeout)
+
+    let res
+    try {
+        res = await fetch(url, {
+            method:  'POST',
+            headers,
+            body:    json,
+            signal:  ac.signal,
+        })
+    } catch (err) {
+        clearTimeout(timer)
+        if (err.name === 'AbortError') {
+            throw new Error(`Handler timeout (${timeout}ms) — ${url}`)
+        }
+        throw new Error(`Handler unreachable: ${err.message} — ${url}`)
+    }
+    clearTimeout(timer)
+
+    if (!res.ok) {
+        const text = await res.text().catch(() => '')
+        throw new Error(`Handler ${res.status} ${res.statusText} — ${text.slice(0, 200)}`)
+    }
+
+    const ct = res.headers.get('content-type') ?? ''
+    if (ct.includes('application/json')) {
+        return await res.json()
+    }
+    // Non-JSON response — wrap as a structured result so the agent
+    // sees something meaningful. The handler is technically off-spec
+    // here (ADR-0008 says return JSON), but we don't punish callers
+    // for a casual `res.send('ok')` from the handler side.
+    const text = await res.text()
+    return { ok: true, handlerResponse: text }
+}
+
 export default ({
     runtime,
     onLoaded,
@@ -322,7 +396,18 @@ export default ({
 
                     // Force the chosen layout — bypass autoLayouts /
                     // layouts.match resolution that onProcessed would do.
-                    const renderEntity = { ...entity, layout: matched }
+                    // Both `entity.layout` AND `entity.meta.layout` need
+                    // to be set: the layouts plugin's onProcessed
+                    // re-resolves entity.layout from entity.meta.layout
+                    // on every cycle, and previewRender goes through
+                    // the full lifecycle. Without overriding meta.layout
+                    // the agent's `mcp-ui/post-approval` choice gets
+                    // silently replaced by the production `post` layout.
+                    const renderEntity = {
+                        ...entity,
+                        layout: matched,
+                        meta: { ...(entity.meta || {}), layout: matched.name },
+                    }
                     const { output } = await previewRender(renderEntity, {
                         save: false,
                         catalog: false,
@@ -350,9 +435,12 @@ export default ({
                             // surface it as text/preformatted.
                             { type: 'text', text: html, mimeType: 'text/html' },
                         ],
-                        // Side-channel metadata so hosts that wire up
-                        // postMessage back-channels know which actions
-                        // the UI emits and which sandbox flags to apply.
+                        // Side-channel metadata so hosts know what to
+                        // do with the rendered UI. Per the MCP Apps
+                        // spec (2026-01-26), the iframe speaks JSON-RPC
+                        // back to the host via postMessage; clicks
+                        // resolve as tools/call against `actionTool`
+                        // (registered with visibility=['app'] below).
                         _meta: {
                             mcpUi: {
                                 layoutId:    matched.id,
@@ -360,6 +448,14 @@ export default ({
                                 description: mcpUiMeta.description ?? null,
                                 actions:     mcpUiMeta.actions     ?? [],
                                 sandbox:     mcpUiMeta.sandbox     ?? ['allow-scripts'],
+                                // The app-callable tool the iframe
+                                // invokes for each user click. Hosts
+                                // that bridge iframe tools/call route
+                                // this through the existing MCP
+                                // transport — the click becomes a
+                                // separate tool turn in the agent's
+                                // conversation.
+                                actionTool:  'mikser_ui_action',
                             },
                         },
                     }
@@ -370,8 +466,112 @@ export default ({
             },
         )
 
+        // mikser_ui_action — app-callable tool that delivers a user
+        // click from inside an mcpUi iframe back to the agent (or to
+        // an external webhook handler).
+        //
+        // Visibility model (MCP Apps spec 2026-01-26):
+        //   _meta.ui.visibility = ['app']
+        //
+        // means this tool is invisible to the agent — it's never
+        // listed in the model's tool surface — but iframes opened by
+        // mikser_preview_ui can invoke it over the host's AppBridge
+        // (tools/call over postMessage). The host bridges the call
+        // into a real MCP tools/call, and the agent sees the result
+        // as a separate tool turn in the conversation.
+        //
+        // Auth boundary: the action MUST appear in the layout's
+        // declared mcpUi.actions list. Unknown actions return an
+        // error result. There is no callId / random URL / signature
+        // on this channel — the iframe's only path to mikser is
+        // through the host's authenticated MCP transport, which is
+        // already trusted.
+        //
+        // Resolution: pure relay (return { entityId, action, payload }
+        // as the tool result) unless the layout declared
+        // mcpUi.handler.url, in which case mikser POSTs the action
+        // to that URL (HMAC-signed if handler.secret is set) and
+        // returns the handler's response. See forwardToHandler above.
+        mcp.registerTool(
+            'mikser_ui_action',
+            {
+                description: 'Deliver a user action emitted from an mcpUi iframe. App-callable only — invisible to the agent, invoked exclusively by iframes opened via mikser_preview_ui. Validates the action against the layout\'s declared mcpUi.actions list, then either returns { entityId, action, payload } as a pure relay or forwards to the layout\'s handler.url webhook if one is declared.',
+                inputSchema: {
+                    entityId: z.string().describe('Entity the action targets (the same id the iframe was rendered for).'),
+                    layoutId: z.string().describe('Layout that rendered the iframe — used to look up the allowed-actions list and optional handler config.'),
+                    action:   z.string().describe('Action name. Must appear in the layout\'s mcpUi.actions list.'),
+                    payload:  z.record(z.any()).optional().describe('Structured payload — form fields, selected status, etc. Schema is layout-defined; mikser passes it through.'),
+                },
+                _meta: {
+                    ui: {
+                        // App-callable only — invisible to the model
+                        // per MCP Apps spec. Hosts MUST NOT include
+                        // it in the agent's tools/list response and
+                        // MUST allow iframes opened via mikser_preview_ui
+                        // to invoke it.
+                        visibility: ['app'],
+                    },
+                },
+            },
+            async ({ entityId, layoutId, action, payload = {} }) => {
+                const logger = useLogger()
+                const fail = (msg) => ({
+                    isError: true,
+                    content: [{ type: 'text', text: msg }],
+                })
+                const ok = (data) => ({
+                    content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+                })
+
+                try {
+                    const layout = await findEntity({ id: layoutId })
+                    if (!layout || layout.collection !== 'layouts') {
+                        return fail(`Layout not found or not a layout: ${layoutId}`)
+                    }
+                    const mcpUiMeta = layout.meta?.mcpUi
+                    if (!mcpUiMeta) {
+                        return fail(`Layout ${layoutId} does not declare mcpUi frontmatter — not eligible as an action source.`)
+                    }
+                    const allowed = mcpUiMeta.actions ?? []
+                    if (!allowed.includes(action)) {
+                        return fail(`Action "${action}" not in allowed list for ${layoutId}. Declared: [${allowed.join(', ')}]`)
+                    }
+
+                    const result = { entityId, action, payload }
+
+                    if (mcpUiMeta.handler?.url) {
+                        try {
+                            const handlerResult = await forwardToHandler(mcpUiMeta.handler, {
+                                ...result,
+                                layoutId,
+                                mode: mcpUiMeta.mode ?? 'preview',
+                            })
+                            logger.debug('MCP mikser_ui_action forwarded %s/%s → %s OK',
+                                entityId, action, mcpUiMeta.handler.url)
+                            return ok(handlerResult)
+                        } catch (err) {
+                            // Fail-safe: never lose the user's click.
+                            // Surface handler failure to the agent as
+                            // structured metadata alongside the relay
+                            // payload so the agent can decide whether
+                            // to retry or proceed without backend ack.
+                            logger.warn('MCP mikser_ui_action handler failed (%s) — falling back to pure relay: %s',
+                                mcpUiMeta.handler.url, err.message)
+                            return ok({ ...result, handlerError: err.message })
+                        }
+                    }
+
+                    logger.debug('MCP mikser_ui_action %s/%s (pure relay)', entityId, action)
+                    return ok(result)
+                } catch (err) {
+                    logger.error('MCP mikser_ui_action error: %s', err.message)
+                    return fail(err.message)
+                }
+            },
+        )
+
         const logger = useLogger()
-        logger.debug('MCP tool registered: mikser_preview_ui + mikser://mcp-ui/modes resource (preview plugin)')
+        logger.debug('MCP tools registered: mikser_preview_ui + mikser_ui_action + mikser://mcp-ui/modes resource (preview plugin)')
     })
 
     return { name: 'preview' }

package/src/plugins/render/file.js

@@ -13,4 +13,33 @@ export function load({ runtime }) {
     runtime.glob = (pattern, options = {}) => {
         return globby.sync(pattern, options)
     }
-}
+
+    // Stringify an arbitrary value as a JSON literal. Use with the
+    // triple-stash form ({{{json …}}}) when embedding inside a
+    // <script> block or HTML attribute — Handlebars's HTML-escape
+    // would otherwise turn quotes into &quot; and break the literal.
+    //
+    //   <script>const id = {{{json document.id}}};</script>
+    //
+    // No SafeString wrap on purpose — that would silently make
+    // double-stash also output raw, which is the foot-gun when the
+    // template author thought they were getting escaping.
+    runtime.json = (value) => JSON.stringify(value)
+
+    // Build an array from positional args. Lets a template construct
+    // an empty array ({{array}}) or a literal list ({{array 1 2 3}})
+    // without a custom helper. Handy as the fallback value in
+    // expressions like (default document.meta.tags (array)).
+    //
+    // Handlebars passes a trailing `options` object to every helper
+    // call; we strip it so the array doesn't end up with a stray
+    // hash/data/fn object as its last element.
+    runtime.array = (...args) => {
+        if (args.length && typeof args[args.length - 1] === 'object'
+            && args[args.length - 1] !== null
+            && 'hash' in args[args.length - 1]) {
+            args = args.slice(0, -1)
+        }
+        return args
+    }
+}