mikser-io 7.12.0 → 7.12.1

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 `postMessage` their click back as the tool result — 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": "7.12.1",
 	"description": "<p align=\"center\">   <img src=\"mikser-lockup-stacked.svg\" alt=\"mikser\" width=\"198\" /> </p>",
 	"main": "index.js",
 	"scripts": {

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

@@ -322,7 +322,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,

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
+    }
+}